block-uuidv7 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ae447bd13b7cd778a06726790f667823627a9b3bac0adbce6d309b3e367b2e3d
+  data.tar.gz: b526111fb89415d3efff2bc315af518c43f9dfb7a432a6363b582bbdd746dc1f
+SHA512:
+  metadata.gz: b4b93d3b5a7aaf4007cf70ada05fc001561d4a9a24df2594a6011fcce0644f74f2a7eae9466323e52ef7bdf302bfb1b8ce8a4aaeaaf34e75454f9e8407006ec6
+  data.tar.gz: 71d36f1e1395312cf3348cc00cb6b254792c3c9836a9e590990f12e7d760325a3161976857b497f6c322fdaa515eeaead9e14e3da0d91aea8e6d5f189bd28189

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,23 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 30
+
+Style/FormatStringToken:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 120

data/AGENTS.md

@@ -0,0 +1,88 @@
+# Agent Guide - Ruby Implementation
+
+For the multi-language overview, see [root AGENTS.md](../AGENTS.md).
+
+## Quick Commands
+
+```bash
+cd ruby
+bundle install    # Install dependencies
+bundle exec rake spec      # Run tests
+bundle exec rake rubocop   # Run linter
+bundle exec rake           # Run both tests and linter
+```
+
+## Prerequisites
+
+- Ruby 3.0 or later
+- Bundler
+
+## Project Structure
+
+```
+ruby/
+├── lib/
+│   ├── uuidv7.rb                    # Main entry point
+│   └── uuidv7/
+│       ├── version.rb               # Version constant
+│       ├── generator.rb             # High-performance UUID v7 (no ordering guarantees)
+│       ├── monotonic_generator.rb   # Monotonic UUID v7 (strict ordering)
+│       └── base62.rb                # Base62 encoding/decoding
+├── spec/
+│   ├── spec_helper.rb
+│   ├── uuidv7_spec.rb
+│   ├── monotonic_uuidv7_spec.rb
+│   └── base62_spec.rb
+├── uuidv7.gemspec
+├── Gemfile
+├── Rakefile
+├── README.md
+└── AGENTS.md  # This file
+```
+
+## Key Implementation Details
+
+### Random Number Generation Strategy
+
+- Uses `SecureRandom` from Ruby stdlib for all random bits
+- Ruby's `rand()` is not thread-safe, so `SecureRandom` is preferred
+- Performance is still excellent for typical use cases
+
+### Monotonic Counter Behavior
+
+- Counter occupies 12 bits (rand_a field): 0-4095
+- Counter increments with each generation in same millisecond
+- Counter resets to **random value** when timestamp advances (not zero!)
+- If counter overflows (4096 in same ms), waits for next millisecond
+- Uses `Mutex` for thread safety
+
+### Thread Safety
+
+- `UUIDv7.generate`: Thread-safe (no shared mutable state)
+- `MonotonicUUIDv7.generate`: Thread-safe via Mutex synchronization
+
+### Clock Injection
+
+Uses block-based clock injection for testability:
+
+```ruby
+UUIDv7.generate { 1700000000000 }
+MonotonicUUIDv7.generate { Time.now.to_i * 1000 }
+```
+
+### Testing Notes
+
+- `MonotonicGenerator.reset_state!` is available for test isolation
+- Always reset state before monotonic tests to ensure deterministic behavior
+
+## Gem Publishing
+
+```bash
+gem build uuidv7.gemspec
+gem push uuidv7-x.x.x.gem
+```
+
+## Further Reading
+
+- [README.md](README.md) - API documentation and usage examples
+- [Root AGENTS.md](../AGENTS.md) - Shared algorithm and design principles

data/README.md

@@ -0,0 +1,163 @@
+# UUIDv7 - Ruby
+
+A minimal, high-performance UUID v7 implementation for Ruby.
+
+## Introduction
+
+[UUID v7](https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7) is a time-ordered UUID format that encodes a Unix timestamp in the most significant 48 bits, making UUIDs naturally sortable by creation time. This is useful for:
+
+- Database indexed fields that benefit from sequential ordering
+- Distributed systems where time-based ordering is valuable
+- Event logs and audit trails where chronological sorting is important
+
+### Compact Base62 Format
+
+**Recommended for APIs, databases, and anywhere IDs are stored or transmitted as text.**
+
+#### Why Compact Strings?
+
+UUIDs are 128-bit values. When you need to store or transmit them, you have two choices:
+
+1. **Binary (16 bytes)**: Most efficient, but not human-readable and requires binary-safe storage
+2. **String**: Human-readable and universally supported, but takes more space
+
+If you must use strings (APIs, URLs, text database columns, JSON, logs), the standard UUID format (`01936c0a-5e0c-7b3a-8f9d-2e1c4a6b8d0f`) uses 36 characters. The compact format reduces this to **22 characters** while preserving all the benefits of UUID v7.
+
+#### How It Works
+
+The compact format uses **Base62 encoding** (digits `0-9`, uppercase `A-Z`, lowercase `a-z`) to represent the 128-bit UUID value. This is similar to how Base64 works, but without special characters like `+`, `/`, or `=`.
+
+```
+Standard:  01936c0a-5e0c-7b3a-8f9d-2e1c4a6b8d0f  (36 chars)
+Compact:   01JDQYZ9M6K7TCJK2F3W8N                (22 chars)
+           ↑
+           Same UUID, different encoding
+```
+
+The encoding preserves **lexicographic ordering**: if UUID A was generated before UUID B, then `compact(A) < compact(B)` in string comparison. This means database indexes on compact strings maintain time-ordering, and APIs can sort by ID to get chronological order.
+
+#### When to Use Compact Strings
+
+| Use Case | Recommended Format |
+|----------|-------------------|
+| Database binary column (BINARY(16), BLOB) | Binary (16 bytes) |
+| Database text/VARCHAR column | **Compact (22 chars)** |
+| REST API responses | **Compact (22 chars)** |
+| URLs and query parameters | **Compact (22 chars)** |
+| Logs and debugging | Standard (36 chars) for readability |
+| Interop with systems expecting standard UUIDs | Standard (36 chars) |
+
+#### Benefits Summary
+
+- **39% shorter** than standard UUID strings (22 vs 36 characters)
+- **Lexicographically sortable** - preserves time-based ordering in databases and APIs
+- **URL-safe** - no special characters, hyphens, or encoding needed
+- **Database-friendly** - smaller indexes, faster queries, less storage
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'uuidv7'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install uuidv7
+```
+
+## Usage
+
+```ruby
+require 'uuidv7'
+
+# Generate a UUID v7 (high performance, no ordering guarantees within same millisecond)
+uuid = UUIDv7.generate
+# => "01936c0a-5e0c-7b3a-8f9d-2e1c4a6b8d0f"
+
+# Generate with monotonic ordering (for database primary keys)
+uuid = MonotonicUUIDv7.generate
+# => "01936c0a-5e0c-7b3a-8f9d-2e1c4a6b8d0f"
+
+# Extract the timestamp (milliseconds since Unix epoch)
+timestamp = UUIDv7.timestamp(uuid)
+# => 1700000000000
+
+# Generate a compact string directly (22 characters, Base62)
+compact_id = UUIDv7.generate_compact
+# => "01JDQYZ9M6K7TCJK2F3W8N"
+
+# Convert UUID to compact string (preserves sort order)
+compact = UUIDv7.to_compact(uuid)
+
+# Convert compact string back to UUID
+uuid = UUIDv7.from_compact(compact)
+
+# Custom clock for testing
+uuid = UUIDv7.generate { 1700000000000 }
+
+# Monotonic with custom clock
+uuid = MonotonicUUIDv7.generate { 1700000000000 }
+```
+
+## Design Principles
+
+**Minimal API Surface**: Simple module methods that return standard UUID strings. No custom UUID class - maximum compatibility with existing code.
+
+**Separate Modules for Different Use Cases**: Two distinct implementations for different performance/ordering trade-offs:
+- **`UUIDv7`**: Maximum performance with no synchronization overhead. UUIDs generated in the same millisecond may not be strictly ordered, but uniqueness is maintained through random bits. Ideal for high-throughput scenarios and distributed systems.
+- **`MonotonicUUIDv7`**: Uses a mutex-protected counter to ensure strict ordering within the same millisecond, following RFC 9562 recommendations. Best for database primary keys and scenarios requiring guaranteed sequential ordering.
+
+**Timestamp Extraction**: UUIDs contain timing information, and this library makes it easy to extract this for debugging, observability, and time-based queries.
+
+**Flexible Generation**: Block-based clock injection for testing or custom time sources.
+
+## API Reference
+
+### UUIDv7 (High Performance, No Ordering Guarantees)
+
+| Method | Description |
+|--------|-------------|
+| `UUIDv7.generate(&clock)` | Generate a new UUID v7 string. Optional block for custom clock. |
+| `UUIDv7.generate_compact(&clock)` | Generate a new UUID v7 as 22-character compact string. |
+| `UUIDv7.timestamp(uuid)` | Extract millisecond timestamp from UUID v7 string. |
+| `UUIDv7.to_compact(uuid)` | Convert UUID string to 22-character compact string. |
+| `UUIDv7.from_compact(compact)` | Convert compact string back to UUID string. |
+
+### MonotonicUUIDv7 (Sequential Ordering Guaranteed)
+
+| Method | Description |
+|--------|-------------|
+| `MonotonicUUIDv7.generate(&clock)` | Generate a new UUID v7 with strict ordering. Optional block for custom clock. |
+| `MonotonicUUIDv7.generate_compact(&clock)` | Generate with strict ordering as compact string. |
+
+## Implementation Details
+
+### Format
+
+UUID v7 follows RFC 9562:
+- **Bits 0-47**: Unix timestamp in milliseconds (48 bits)
+- **Bits 48-51**: Version field (0111 for v7)
+- **Bits 52-63**: Counter or random bits (12 bits, called `rand_a`)
+- **Bits 64-65**: Variant field (10 for RFC 4122)
+- **Bits 66-127**: Random bits (62 bits, called `rand_b`)
+
+### Monotonic Counter Behavior
+
+- Counter occupies 12 bits (rand_a field): 0-4095
+- Counter increments with each generation in same millisecond
+- Counter resets to **random value** when timestamp advances
+- If counter overflows (4096 in same ms), waits for next millisecond
+- Thread-safe via Mutex synchronization
+
+## License
+
+Apache-2.0

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/block-uuidv7.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'lib/uuidv7/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'block-uuidv7'
+  spec.version = UUIDv7::VERSION
+  spec.authors = ['Block, Inc.']
+  spec.email = ['opensource@block.xyz']
+
+  spec.summary = 'A minimal, high-performance UUID v7 implementation for Ruby'
+  spec.description = 'UUID v7 is a time-ordered UUID format that encodes a Unix timestamp in the most significant ' \
+                     '48 bits, making UUIDs naturally sortable by creation time. This library provides both ' \
+                     'high-performance and monotonic (strictly ordered) variants.'
+  spec.homepage = 'https://github.com/block/uuidv7'
+  spec.license = 'Apache-2.0'
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/block/uuidv7/tree/main/ruby'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+end

data/lib/uuidv7/base62.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module UUIDv7
+  module Base62
+    ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+    BASE = 62
+    COMPACT_LENGTH = 22
+
+    class << self
+      def encode(uuid)
+        raise InvalidUUIDError, 'UUID cannot be nil' if uuid.nil?
+
+        hex = uuid.delete('-')
+        raise InvalidUUIDError, 'Invalid UUID format' unless hex.match?(/\A[0-9a-f]{32}\z/i)
+
+        value = hex.to_i(16)
+        result = []
+
+        while value.positive?
+          value, remainder = value.divmod(BASE)
+          result << ALPHABET[remainder]
+        end
+
+        result << '0' while result.length < COMPACT_LENGTH
+
+        result.reverse.join
+      end
+
+      def decode(compact_string)
+        raise InvalidCompactStringError, 'Compact string cannot be nil' if compact_string.nil?
+
+        unless compact_string.length == COMPACT_LENGTH
+          raise InvalidCompactStringError,
+                "Compact string must be exactly #{COMPACT_LENGTH} characters (got #{compact_string.length})"
+        end
+
+        value = 0
+        compact_string.each_char do |char|
+          digit = ALPHABET.index(char)
+          raise InvalidCompactStringError, "Invalid compact string character: #{char}" if digit.nil?
+
+          value = (value * BASE) + digit
+        end
+
+        msb = (value >> 64) & 0xFFFFFFFFFFFFFFFF
+        lsb = value & 0xFFFFFFFFFFFFFFFF
+
+        hex = format('%016x%016x', msb, lsb)
+        "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+      end
+    end
+  end
+end

data/lib/uuidv7/generator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module UUIDv7
+  module Generator
+    class << self
+      def generate(&clock)
+        timestamp = clock ? clock.call : (Time.now.to_f * 1000).to_i
+        rand_a = rand(4096)
+        rand_b = SecureRandom.random_number(2**62)
+
+        build(timestamp, rand_a, rand_b)
+      end
+
+      def generate_compact(&clock)
+        Base62.encode(generate(&clock))
+      end
+
+      def timestamp(uuid)
+        raise InvalidUUIDError, 'UUID cannot be nil' if uuid.nil?
+
+        hex = uuid.delete('-')
+        raise InvalidUUIDError, 'Invalid UUID format' unless hex.match?(/\A[0-9a-f]{32}\z/i)
+
+        msb = hex[0, 16].to_i(16)
+        version = (msb >> 12) & 0xF
+
+        raise InvalidUUIDError, "UUID is not version 7 (got version #{version})" unless version == 7
+
+        msb >> 16
+      end
+
+      def build(timestamp, rand_a, rand_b)
+        rand_a &= 0xFFF
+
+        msb = (timestamp << 16) | rand_a
+        lsb = rand_b
+
+        msb = (msb & 0xFFFFFFFFFFFF0FFF) | 0x0000000000007000
+        lsb = (lsb & 0x3FFFFFFFFFFFFFFF) | 0x8000000000000000
+
+        format_uuid(msb, lsb)
+      end
+
+      private
+
+      def format_uuid(msb, lsb)
+        hex = format('%016x%016x', msb, lsb)
+        "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+      end
+    end
+  end
+end

data/lib/uuidv7/monotonic_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module UUIDv7
+  module MonotonicGenerator
+    COUNTER_MAX = 0xFFF # 12 bits = 4095
+
+    @mutex = Mutex.new
+    @last_timestamp = 0
+    @counter = 0
+
+    class << self
+      def generate(&clock)
+        @mutex.synchronize do
+          timestamp = clock ? clock.call : (Time.now.to_f * 1000).to_i
+          counter_value = nil
+
+          if timestamp == @last_timestamp
+            @counter = (@counter + 1) & COUNTER_MAX
+
+            if @counter.zero?
+              loop do
+                timestamp = clock ? clock.call : (Time.now.to_f * 1000).to_i
+                break if timestamp != @last_timestamp
+
+                sleep(0.0001) unless clock
+              end
+              @counter = SecureRandom.random_number(COUNTER_MAX + 1)
+            end
+            counter_value = @counter
+          else
+            @counter = SecureRandom.random_number(COUNTER_MAX + 1)
+            counter_value = @counter
+            @last_timestamp = timestamp
+          end
+
+          rand_b = SecureRandom.random_number(2**62)
+          Generator.build(timestamp, counter_value, rand_b)
+        end
+      end
+
+      def generate_compact(&clock)
+        Base62.encode(generate(&clock))
+      end
+
+      def reset_state!
+        @mutex.synchronize do
+          @last_timestamp = 0
+          @counter = 0
+        end
+      end
+    end
+  end
+end

data/lib/uuidv7/version.rb

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

data/lib/uuidv7.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'uuidv7/version'
+require_relative 'uuidv7/base62'
+require_relative 'uuidv7/generator'
+require_relative 'uuidv7/monotonic_generator'
+
+module UUIDv7
+  class Error < StandardError; end
+  class InvalidUUIDError < Error; end
+  class InvalidCompactStringError < Error; end
+
+  class << self
+    def generate(&clock)
+      Generator.generate(&clock)
+    end
+
+    def generate_compact(&clock)
+      Generator.generate_compact(&clock)
+    end
+
+    def timestamp(uuid)
+      Generator.timestamp(uuid)
+    end
+
+    def to_compact(uuid)
+      Base62.encode(uuid)
+    end
+
+    def from_compact(compact_string)
+      Base62.decode(compact_string)
+    end
+  end
+end
+
+module MonotonicUUIDv7
+  class << self
+    def generate(&clock)
+      UUIDv7::MonotonicGenerator.generate(&clock)
+    end
+
+    def generate_compact(&clock)
+      UUIDv7::MonotonicGenerator.generate_compact(&clock)
+    end
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: block-uuidv7
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Block, Inc.
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-01-29 00:00:00.000000000 Z
+dependencies: []
+description: UUID v7 is a time-ordered UUID format that encodes a Unix timestamp in
+  the most significant 48 bits, making UUIDs naturally sortable by creation time.
+  This library provides both high-performance and monotonic (strictly ordered) variants.
+email:
+- opensource@block.xyz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- AGENTS.md
+- README.md
+- Rakefile
+- block-uuidv7.gemspec
+- lib/uuidv7.rb
+- lib/uuidv7/base62.rb
+- lib/uuidv7/generator.rb
+- lib/uuidv7/monotonic_generator.rb
+- lib/uuidv7/version.rb
+homepage: https://github.com/block/uuidv7
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/block/uuidv7
+  source_code_uri: https://github.com/block/uuidv7/tree/main/ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: A minimal, high-performance UUID v7 implementation for Ruby
+test_files: []