uxid 0.2.3 → 1.0.0

data/lib/uxid.rb

@@ -1,68 +1,162 @@
-# frozen-string-literal: true
-
-if RUBY_VERSION >= "2.5"
-  require "securerandom"
-else
-  require "sysrandom/securerandom"
-end
-
-require "uxid/model"
-require "uxid/encoder"
-require "uxid/version"
-
+# frozen_string_literal: true
+
+require_relative "uxid/version"
+require_relative "uxid/error"
+require_relative "uxid/options"
+require_relative "uxid/encoder"
+require_relative "uxid/decoded"
+require_relative "uxid/decoder"
+require_relative "uxid/monotonic"
+
+# Prefixed, K-sortable identifiers, wire-compatible with the Elixir
+# reference implementation of uxid.
 module UXID
-  CROCKFORD_ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
-  DELIMITER = "_"
-
-  SIZE_WARNING_MESSAGE = <<-EOM
-WARN: The UXID :size param is for Symbol T-Shirt sizes only.
-      Please use the :size param with Symbols (:xs, :s, :m, :l, :xl, or :xsmall, :small, :medium, :large, :xlarge),
-      or use the :rand_size param for specific size of random bytes.
-  EOM
-
-  class Error < StandardError; end
-
-  def self.generate attrs = {}
-    model = new attrs
-    model.encode
+  # Generates an id: an optional prefix and delimiter, then a body in
+  # Crockford Base32, laid out as uxid-ex's wire-format spec defines it. The
+  # body is time-based (a time field and a random field) unless :from is
+  # given, when it is deterministic: the marker character (z, or Z in an
+  # upper-case id) and then a SHA-256 hash of the prefix, the from string
+  # and the size, so the same arguments always give the same id. A
+  # deterministic id sorts after every time-based id with its prefix and
+  # case.
+  #
+  # Every option is a keyword argument; an option left out takes its default,
+  # and an unknown one raises ArgumentError. The options whose default is nil
+  # take nil; the others refuse it.
+  #
+  # @param options [Hash] the keyword arguments below
+  # @option options [String, nil] :prefix (nil) the prefix, emitted as given;
+  #   nil and an empty string are both no prefix, and the id is then the bare
+  #   body
+  # @option options [Symbol, String] :size (:xl) :xs, :s, :m, :l or :xl, or
+  #   their long names :xsmall, :small, :medium, :large and :xlarge, as
+  #   Symbols or Strings
+  # @option options [Integer, nil] :rand_size (nil) the random field's width
+  #   in bytes, 0 to 10, in place of the size's; a body whose width is not the
+  #   size table's has a length a decoder refuses
+  # @option options [Boolean] :compact_time (false) true for compact time (the
+  #   low 40 bits of the time in 8 characters), false for standard time (48
+  #   bits in 10)
+  # @option options [Symbol, String] :case (:lower) :lower or :upper, the case
+  #   of every body character; the prefix keeps its own
+  # @option options [String] :delimiter ("_") the non-empty string between
+  #   prefix and body
+  # @option options [Integer, Time, nil] :time (nil) the time, as milliseconds
+  #   since the Unix epoch (0 to 2**48 - 1) or a Time (read to the
+  #   millisecond); nil reads the system clock
+  # @option options [String, nil] :rand (nil) the random field's bytes, used
+  #   verbatim. For reproducible ids such as test vectors only, never as a
+  #   source of randomness: the id is exactly as guessable as these bytes.
+  #   Its byte size must be the call's random width
+  # @option options [#call, nil] :byte_source (nil) where the random field's
+  #   bytes come from: any object whose call(count) returns a String of count
+  #   bytes; nil is SecureRandom.random_bytes. Not called when :rand is given
+  # @option options [String, nil] :from (nil) the string a deterministic body
+  #   is the hash of, read as its bytes: valid text in an encoding other
+  #   than UTF-8 is transcoded to UTF-8 first; a binary (ASCII-8BIT) String,
+  #   one not valid in its own encoding, and one Ruby cannot transcode are
+  #   hashed as their own bytes, so a raw-byte key such as a 16-byte UUID
+  #   works. The prefix is hashed the same way. The body has the size's
+  #   standard length; :time, :compact_time, :rand_size and :byte_source do
+  #   not apply to it and are not read
+  # @return [String] the id
+  # @raise [UXID::Error] a refusal the wire format names, with its
+  #   {UXID::Error#code}: :rand_size_too_large for a :rand_size above 10,
+  #   :rand_width_mismatch for a :rand whose byte size is not the random
+  #   width, :compact_time_out_of_range for a compact time whose first
+  #   character would be the deterministic marker, :rand_with_from for a
+  #   :rand given with :from
+  # @raise [ArgumentError] any other option outside the ones above
+  #
+  # @example
+  #   UXID.generate(prefix: "usr")             # => "usr_01..." (26 body characters)
+  #   UXID.generate(prefix: "cus", size: :s)   # => "cus_01..." (14 body characters)
+  #   UXID.generate(prefix: "usr", size: :xs, time: 1_700_000_000_000)
+  #   # => "usr_01hf7yat00"
+  #   UXID.generate(prefix: "cus", from: "acme-corp", size: :s)
+  #   # => "cus_zt9vnyfd85bff0"
+  def self.generate(**options)
+    Encoder.generate(Options.resolve(options))
   end
 
-  def self.new attrs = {}
-    model = ::UXID::Model.new
-
-    model.time = attrs[:time] || Time.now
-    model.prefix = attrs[:prefix] || ""
-    model.size = attrs[:size]
-
-    if attrs[:rand_size]
-      model.rand_size = attrs[:rand_size]
-    else
-      case model.size
-      when Integer
-        puts SIZE_WARNING_MESSAGE
-        model.rand_size = model.size
-
-      when String
-        puts SIZE_WARNING_MESSAGE
-        model.rand_size = 10
-
-      when :xs, :xsmall
-        model.rand_size = 0
-
-      when :s, :small
-        model.rand_size = 2
-
-      when :m, :medium
-        model.rand_size = 5
-
-      when :l, :large
-        model.rand_size = 7
+  # Decodes an id: its prefix, its size and time form, whether it is
+  # deterministic, and its time, as uxid-ex's wire-format spec reads them.
+  # The random field is not read back.
+  #
+  # The body is everything after the last delimiter and the prefix
+  # everything before it; an id with no delimiter is a body with no prefix.
+  # The body length in bytes gives the size and the time form. The lengths
+  # 10 and 18 are read as standard xs and standard m: a compact xs or compact
+  # m id decodes to its size but not its time. A body starting with z or Z
+  # is deterministic and has no time. A compact body carries the low 40 bits
+  # of its time; the rest come from the decoder's clock, and a result more
+  # than one day ahead of the clock is taken from the 2**40 ms window before.
+  #
+  # Malformed input never raises: a String the format refuses gives an
+  # Invalid whose reason is the first rule it fails, in this order: :empty
+  # (an empty body: an empty string, or one ending in the delimiter),
+  # :invalid_length (a body length in bytes not in the length table),
+  # :invalid_character (a body byte outside the alphabet in either case).
+  # A value that is not a String has no alphabet characters and gives
+  # :invalid_character. A String in any encoding, binary or not valid in its
+  # own encoding included, is read as its bytes.
+  #
+  # @param id [Object] the id to read
+  # @param delimiter [String] ("_") the non-empty string between prefix and
+  #   body; it must be the one the id was generated with
+  # @param now [Integer, Time, nil] (nil) the decoder's clock, as
+  #   milliseconds since the Unix epoch or a Time, read only for a compact
+  #   time; nil reads the system clock
+  # @return [UXID::Decoded, UXID::Invalid] both answer valid?, true for a
+  #   Decoded and false for an Invalid
+  # @raise [ArgumentError] for a delimiter that is not a non-empty String,
+  #   or a now that is not an Integer, a Time or nil
+  #
+  # @example
+  #   UXID.decode("usr_01hf7yat00")
+  #   # => #<data UXID::Decoded prefix="usr", size=:xs, compact=false, deterministic=false, time=1700000000000>
+  #   UXID.decode("cus_zt9vnyfd85bff0").deterministic? # => true
+  #   UXID.decode("usr_01hf7yat0").reason              # => :invalid_length
+  def self.decode(id, delimiter: "_", now: nil)
+    Decoder.decode(id, delimiter, now)
+  end
 
-      else
-        model.rand_size = 10
-      end
-    end
+  # Whether an id decodes (see UXID.decode) and, when :prefix is given, has
+  # exactly that prefix. Never raises on the id: anything UXID.decode
+  # refuses, a value that is not a String included, is false.
+  #
+  # @param id [Object] the id to check
+  # @param prefix [String, nil] (nil) the prefix the id must have; nil and
+  #   the empty string accept any prefix or none
+  # @param delimiter [String] ("_") the non-empty string between prefix and
+  #   body
+  # @return [Boolean]
+  # @raise [ArgumentError] for a delimiter that is not a non-empty String
+  #
+  # @example
+  #   UXID.valid?("cus_zt9vnyfd85bff0")                 # => true
+  #   UXID.valid?("cus_zt9vnyfd85bff0", prefix: "usr")  # => false
+  #   UXID.valid?("usr_01hu7yat00")                     # => false
+  def self.valid?(id, prefix: nil, delimiter: "_")
+    decoded = Decoder.decode(id, delimiter, nil)
+    decoded.valid? && (prefix.nil? || prefix.empty? || decoded.prefix == prefix)
+  end
 
-    model
+  # Whether an id decodes (see UXID.decode) to a deterministic body, one
+  # generated with :from. Never raises on the id: anything UXID.decode
+  # refuses, a value that is not a String included, is false.
+  #
+  # @param id [Object] the id to check
+  # @param delimiter [String] ("_") the non-empty string between prefix and
+  #   body
+  # @return [Boolean]
+  # @raise [ArgumentError] for a delimiter that is not a non-empty String
+  #
+  # @example
+  #   UXID.deterministic?("cus_zt9vnyfd85bff0") # => true
+  #   UXID.deterministic?("usr_01hf7yat00")     # => false
+  def self.deterministic?(id, delimiter: "_")
+    decoded = Decoder.decode(id, delimiter, nil)
+    decoded.valid? && decoded.deterministic?
   end
 end

metadata

@@ -1,53 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: uxid
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 1.0.0
 platform: ruby
 authors:
 - JohnnyT
-autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2020-11-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: 'Generates IDs like: cus_01EPEY1JMK and txn_01EPEY2P06TR1RTV07 (similar
-  to Stripe identifiers).'
+description: Generates and decodes prefixed, K-sortable identifiers a person can read,
+  copy and route back to their resource. Random, deterministic and monotonic generation,
+  decoding and validity checks, checked against the conformance corpus of the Elixir
+  reference implementation. No runtime dependencies.
 email:
 - ubergeek3141@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/build.yml"
-- ".gitignore"
-- ".rubocop.yml"
-- ".simplecov"
 - CHANGELOG.md
-- Dangerfile
-- Gemfile
-- Gemfile.lock
 - LICENSE
 - README.md
-- Rakefile
-- bin/console
-- bin/setup
-- lib/tasks/bundler.rake
-- lib/tasks/check.rake
-- lib/tasks/linting.rake
-- lib/tasks/quality.rake
-- lib/tasks/test.rake
 - lib/uxid.rb
+- lib/uxid/decoded.rb
+- lib/uxid/decoder.rb
 - lib/uxid/encoder.rb
-- lib/uxid/model.rb
+- lib/uxid/error.rb
+- lib/uxid/monotonic.rb
+- lib/uxid/options.rb
 - lib/uxid/version.rb
-- uxid.gemspec
 homepage: https://github.com/riddler/uxid-rb
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/riddler/uxid-rb
   source_code_uri: https://github.com/riddler/uxid-rb
-post_install_message:
+  changelog_uri: https://github.com/riddler/uxid-rb/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -55,16 +45,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
-signing_key:
+rubygems_version: 4.0.20
 specification_version: 4
-summary: 'Generates IDs like: cus_01EPEY1JMK and txn_01EPEY2P06TR1RTV07 (similar to
-  Stripe identifiers).'
+summary: Prefixed, K-sortable identifiers, wire-compatible with the Elixir uxid.
 test_files: []

data/.github/workflows/build.yml

@@ -1,72 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches:
-      - main
-
-jobs:
-  danger:
-    runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request' # only run pull request when multiple trigger workflow
-    steps:
-    - name: Checkout Repo
-      uses: actions/checkout@v2
-
-    - name: Setup Ruby
-      uses: actions/setup-ruby@v1
-      with:
-        ruby-version: '2.6'
-
-    - name: Cache Ruby Gems
-      uses: actions/cache@v2
-      with:
-        path: vendor/bundle
-        key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
-        restore-keys: |
-          ${{ runner.os }}-gems-
-
-    - name: Bundle Install
-      run: |
-        bundle config path vendor/bundle
-        bundle install --jobs 4 --retry 3
-
-    - name: Danger linting
-      uses: MeilCli/danger-action@v5
-      with:
-        plugins_file: Gemfile
-        install_path: vendor/bundle
-        danger_file: Dangerfile
-        danger_id: danger-pr
-      env:
-        DANGER_GITHUB_API_TOKEN: ${{ secrets.DANGER_GITHUB_API_TOKEN }}
-
-  tests:
-    runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request' # only run pull request when multiple trigger workflow
-    steps:
-    - name: Checkout Repo
-      uses: actions/checkout@v2
-
-    - name: Setup Ruby
-      uses: actions/setup-ruby@v1
-      with:
-        ruby-version: '2.6'
-
-    - name: Cache Ruby Gems
-      uses: actions/cache@v2
-      with:
-        path: vendor/bundle
-        key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
-        restore-keys: |
-          ${{ runner.os }}-gems-
-
-    - name: Bundle Install
-      run: |
-        bundle config path vendor/bundle
-        bundle install --jobs 4 --retry 3
-
-    - name: Run Tests
-      run: |
-        bundle config path vendor/bundle
-        bundle exec rake test

data/.gitignore

@@ -1,43 +0,0 @@
-# Custom files
-
-# Compiled source
-*.com
-*.class
-*.dll
-*.exe
-*.o
-*.so
-
-# Packages
-#
-# It's better to unpack these files and commit the raw source
-# git has its own built in compression methods
-*.7z
-*.dmg
-*.gz
-*.iso
-*.jar
-*.rar
-*.tar
-*.zip
-
-# Logs and databases
-*.log
-*.sql
-*.sqlite
-
-# OS generated files #
-.DS_Store
-.DS_Store?
-._*
-.Spotlight-V100
-.Trashes
-ehthumbs.db
-Thumbs.db
-
-# Editor-made files
-*.swp
-
-#===== Ruby =====
-*.gem
-reports/

data/.rubocop.yml

@@ -1,103 +0,0 @@
-AllCops:
-  TargetRubyVersion: 2.5
-  DisabledByDefault: true
-  Exclude:
-    - pkg/**/*.rb
-    - test/spec/**/*.rb
-
-Bundler/DuplicatedGem:
-  Enabled: true
-Lint:
-  Enabled: true
-Security:
-  Enabled: true
-
-# Single quotes being faster is hardly measurable and only affects parse time.
-# Enforcing double quotes reduces the times where you need to change them
-# when introducing an interpolation. Use single quotes only if their semantics
-# are needed.
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-  Exclude:
-    - lib/riddler/protobuf/*_pb.rb
-
-# Seattle style
-Style/MethodDefParentheses:
-  EnforcedStyle: require_no_parentheses
-
-# Seattle style
-Style/MethodCallWithoutArgsParentheses:
-  Enabled: true
-
-# Seattle style
-Style/MethodCallWithArgsParentheses:
-  Enabled: true
-  EnforcedStyle: omit_parentheses
-  AllowParenthesesInChaining: true
-  IgnoredMethods:
-    - watch
-
-Style/SpecialGlobalVars:
-  Enabled: false
-
-Layout/FirstArrayElementIndentation:
-  Enabled: true
-  EnforcedStyle: consistent
-
-Style/Lambda:
-  Enabled: true
-  EnforcedStyle: literal
-
-# Allow regex argument in Seattle style
-Lint/AmbiguousRegexpLiteral:
-  Enabled: false
-
-# Allow block argument in Seattle style
-Lint/AmbiguousOperator:
-  Enabled: false
-
-Layout/SpaceInsideHashLiteralBraces:
-  Enabled: true
-  EnforcedStyleForEmptyBraces: no_space
-  EnforcedStyle: no_space
-
-Layout/FirstHashElementIndentation:
-  Enabled: true
-  EnforcedStyle: consistent
-
-Layout/CaseIndentation:
-  Enabled: true
-  EnforcedStyle: end
-
-Layout/EndAlignment:
-  Enabled: true
-  EnforcedStyleAlignWith: variable
-
-Layout/SpaceAroundBlockParameters:
-  Enabled: true
-
-Layout/SpaceBeforeBlockBraces:
-  Enabled: true
-
-Layout/SpaceInsideBlockBraces:
-  Enabled: true
-
-Layout/LineLength:
-  Enabled: true
-  Max: 120
-  Exclude:
-    - lib/riddler/protobuf/*_pb.rb
-
-Metrics/ClassLength:
-  Enabled: true
-  Max: 200
-  Exclude:
-    - test/**/*.rb
-
-Lint/SuppressedException:
-  Exclude:
-    - lib/tasks/**/*.rake
-
-Lint/Debugger:
-  Exclude:
-    - test/**/*

data/.simplecov

@@ -1,8 +0,0 @@
-SimpleCov.start do
-  coverage_dir "reports/coverage"
-
-  add_filter "/config/"
-  add_filter "/lib/tasks/"
-
-  track_files "lib/**/*.rb"
-end

data/Dangerfile

@@ -1,5 +0,0 @@
-# Check format of commit message
-commit_lint.check fail: :all
-
-# Make it more obvious that a PR is a work in progress and shouldn't be merged yet
-warn "PR is classed as Work in Progress" if github.pr_title.include? "[WIP]"

data/Gemfile

@@ -1,15 +0,0 @@
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in uxid.gemspec
-gemspec
-
-gem "danger"
-gem "danger-commit_lint"
-gem "minitest", "~> 5.0"
-gem "minitest-focus"
-gem "minitest-reporters"
-gem "pry-nav"
-gem "rake", "~> 12.0"
-gem "rubycritic", require: false
-gem "rubocop"
-gem "simplecov", require: false