opaque_id 1.2.0 → 1.4.0

data/docs/getting-started.md

@@ -0,0 +1,259 @@
+---
+layout: default
+title: Getting Started
+nav_order: 2
+description: "Quick setup and basic usage guide for OpaqueId"
+permalink: /getting-started/
+---
+
+# Getting Started
+
+This guide will help you get up and running with OpaqueId in your Rails application. We'll cover installation, basic setup, and common usage patterns.
+
+- TOC
+  {:toc}
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- **Ruby 3.2+** - OpaqueId requires modern Ruby features
+- **Rails 8.0+** - Built for the latest Rails version
+- **ActiveRecord 8.0+** - For model integration
+
+## Installation
+
+### Step 1: Add to Gemfile
+
+Add OpaqueId to your application's Gemfile:
+
+```ruby
+gem 'opaque_id'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+### Step 2: Generate Migration and Update Model
+
+Use the Rails generator to set up OpaqueId for a specific model:
+
+```bash
+rails generate opaque_id:install User
+```
+
+This command will:
+
+- Create a migration to add the `opaque_id` column
+- Add a unique index on the `opaque_id` column
+- Include the `OpaqueId::Model` concern in your model
+
+### Step 3: Run Migration
+
+Execute the migration:
+
+```bash
+rails db:migrate
+```
+
+### Step 4: Verify Setup
+
+Check that your model has been updated correctly:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  include OpaqueId::Model
+end
+```
+
+## Basic Usage
+
+### Creating Records
+
+Once set up, OpaqueId automatically generates opaque IDs when you create new records:
+
+```ruby
+# Create a new user
+user = User.create!(name: "John Doe", email: "john@example.com")
+
+# The opaque_id is automatically generated
+puts user.opaque_id
+# => "V1StGXR8_Z5jdHi6B-myT"
+```
+
+### Finding Records
+
+Use the provided finder methods to locate records by their opaque ID:
+
+```ruby
+# Find by opaque_id (returns nil if not found)
+user = User.find_by_opaque_id("V1StGXR8_Z5jdHi6B-myT")
+
+# Find by opaque_id (raises exception if not found)
+user = User.find_by_opaque_id!("V1StGXR8_Z5jdHi6B-myT")
+```
+
+### Standalone ID Generation
+
+You can also generate opaque IDs without ActiveRecord:
+
+```ruby
+# Generate a default opaque ID (21 characters, alphanumeric)
+id = OpaqueId.generate
+# => "V1StGXR8_Z5jdHi6B-myT"
+
+# Generate with custom length
+id = OpaqueId.generate(size: 10)
+# => "V1StGXR8_Z5"
+
+# Generate with custom alphabet
+id = OpaqueId.generate(alphabet: OpaqueId::STANDARD_ALPHABET)
+# => "V1StGXR8_Z5jdHi6B-myT"
+```
+
+## Common Patterns
+
+### API Endpoints
+
+Use opaque IDs in your API endpoints for better security:
+
+```ruby
+# routes.rb
+resources :users, param: :opaque_id
+
+# controller
+class UsersController < ApplicationController
+  def show
+    @user = User.find_by_opaque_id!(params[:id])
+  end
+end
+```
+
+### URL Generation
+
+Generate URLs using opaque IDs:
+
+```ruby
+# Instead of exposing internal IDs
+user_path(user) # => /users/123
+
+# Use opaque IDs
+user_path(user.opaque_id) # => /users/V1StGXR8_Z5jdHi6B-myT
+```
+
+### Custom Column Names
+
+If you prefer a different column name, specify it during generation:
+
+```bash
+rails generate opaque_id:install User --column-name=public_id
+```
+
+This will:
+
+- Create a `public_id` column instead of `opaque_id`
+- Add the configuration to your model automatically
+
+## Configuration Options
+
+OpaqueId is highly configurable. Here are the most common options:
+
+### Model-Level Configuration
+
+```ruby
+class User < ApplicationRecord
+  include OpaqueId::Model
+
+  # Custom column name
+  self.opaque_id_column = :public_id
+
+  # Custom length (default: 21)
+  self.opaque_id_length = 15
+
+  # Custom alphabet (default: ALPHANUMERIC_ALPHABET)
+  self.opaque_id_alphabet = OpaqueId::STANDARD_ALPHABET
+
+  # Require letter start (default: false)
+  self.opaque_id_require_letter_start = true
+
+  # Max retry attempts for collision handling (default: 3)
+  self.opaque_id_max_retry = 5
+end
+```
+
+### Global Configuration
+
+You can also configure OpaqueId globally in an initializer:
+
+```ruby
+# config/initializers/opaque_id.rb
+OpaqueId.configure do |config|
+  config.default_length = 15
+  config.default_alphabet = OpaqueId::STANDARD_ALPHABET
+end
+```
+
+## Built-in Alphabets
+
+OpaqueId comes with two pre-configured alphabets:
+
+### ALPHANUMERIC_ALPHABET (Default)
+
+- **Characters**: `A-Z`, `a-z`, `0-9` (62 characters)
+- **Use case**: General purpose, URL-safe
+- **Example**: `V1StGXR8_Z5jdHi6B-myT`
+
+### STANDARD_ALPHABET
+
+- **Characters**: `A-Z`, `a-z`, `0-9`, `-`, `_` (64 characters)
+- **Use case**: When you need the fastest generation
+- **Example**: `V1StGXR8_Z5jdHi6B-myT`
+
+## Error Handling
+
+OpaqueId provides comprehensive error handling:
+
+```ruby
+begin
+  user = User.create!(name: "John Doe")
+rescue OpaqueId::GenerationError => e
+  # Handle ID generation failure (very rare)
+  Rails.logger.error "Failed to generate opaque ID: #{e.message}"
+end
+```
+
+## Next Steps
+
+Now that you have OpaqueId set up, you might want to explore:
+
+- [Installation](installation.md) - Detailed installation guide
+- [Usage](usage.md) - Comprehensive usage examples
+- [Configuration](configuration.md) - Detailed configuration guide
+- [Alphabets](alphabets.md) - Built-in alphabets and custom options
+- [API Reference](api-reference.md) - Complete API documentation
+- [Use Cases](use-cases.md) - Real-world examples and applications
+- [Performance](performance.md) - Benchmarks and optimization tips
+- [Security](security.md) - Security considerations and best practices
+
+## Troubleshooting
+
+### Common Issues
+
+**Migration fails**: Ensure you're using Rails 8.0+ and have the correct database permissions.
+
+**Generator not found**: Make sure you've added `gem 'opaque_id'` to your Gemfile and run `bundle install`.
+
+**ID generation fails**: This is extremely rare, but if it happens, check your database constraints and ensure the column allows the configured length.
+
+### Getting Help
+
+If you encounter issues:
+
+1. Check the [API Reference](api-reference.md) for detailed method documentation
+2. Review the [Usage](usage.md) guide for common patterns
+3. Check the [Use Cases](use-cases.md) for real-world examples
+4. Open an issue on [GitHub](https://github.com/nyaggah/opaque_id/issues) with details about your setup and the error

data/docs/index.md

@@ -0,0 +1,135 @@
+---
+layout: default
+title: Home
+nav_order: 1
+description: "Generate cryptographically secure, collision-free opaque IDs for ActiveRecord models"
+permalink: /
+---
+
+# OpaqueId
+
+[![Gem Version](https://badge.fury.io/rb/opaque_id.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/opaque_id)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
+[![Gem Downloads](https://img.shields.io/badge/gem%20downloads-opaque_id-blue)](https://rubygems.org/gems/opaque_id)
+
+A Ruby gem for generating cryptographically secure, collision-free opaque IDs for ActiveRecord models. OpaqueId provides a drop-in replacement for `nanoid.rb` using Ruby's built-in `SecureRandom` methods with optimized algorithms for unbiased distribution.
+
+- TOC
+  {:toc}
+
+## Features
+
+- **🔐 Cryptographically Secure**: Uses Ruby's `SecureRandom` for secure ID generation
+- **⚡ High Performance**: Optimized algorithms with fast paths for 64-character alphabets
+- **🎯 Collision-Free**: Built-in collision detection with configurable retry attempts
+- **🔧 Highly Configurable**: Customizable alphabet, length, column name, and validation rules
+- **🚀 Rails Integration**: Seamless ActiveRecord integration with automatic ID generation
+- **📦 Rails Generator**: One-command setup with `rails generate opaque_id:install`
+- **🧪 Well Tested**: Comprehensive test suite with statistical uniformity tests
+- **📚 Rails 8.0+ Compatible**: Built for modern Rails applications
+
+## Quick Start
+
+### 1. Add to your Gemfile
+
+```ruby
+gem 'opaque_id'
+```
+
+### 2. Generate migration and update model
+
+```bash
+rails generate opaque_id:install User
+```
+
+### 3. Run migration
+
+```bash
+rails db:migrate
+```
+
+### 4. Use in your models
+
+```ruby
+class User < ApplicationRecord
+  include OpaqueId::Model
+end
+
+# Create a user - opaque_id is automatically generated
+user = User.create!(name: "John Doe")
+puts user.opaque_id # => "V1StGXR8_Z5jdHi6B-myT"
+
+# Find by opaque_id
+user = User.find_by_opaque_id("V1StGXR8_Z5jdHi6B-myT")
+```
+
+## Why OpaqueId?
+
+OpaqueId replaces the need for `nanoid.rb` by providing:
+
+- **Native Ruby implementation** using `SecureRandom`
+- **Better performance** with optimized algorithms
+- **Rails 8.0+ compatibility** out of the box
+- **ActiveRecord integration** with automatic ID generation
+- **Collision handling** with configurable retry attempts
+- **Flexible configuration** for different use cases
+
+## Installation
+
+### Requirements
+
+- Ruby 3.2+
+- Rails 8.0+
+- ActiveRecord 8.0+
+
+### Using Bundler (Recommended)
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'opaque_id'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+### Manual Installation
+
+```bash
+gem install opaque_id
+```
+
+## Getting Started
+
+Ready to get started? Check out our [Getting Started Guide](getting-started.md) for a comprehensive walkthrough.
+
+## Documentation
+
+- [Getting Started](getting-started.md) - Quick setup and basic usage
+- [Installation](installation.md) - Detailed installation guide
+- [Usage](usage.md) - Comprehensive usage examples
+- [Configuration](configuration.md) - All configuration options
+- [Alphabets](alphabets.md) - Built-in alphabets and custom options
+- [Algorithms](algorithms.md) - Technical algorithm details
+- [Performance](performance.md) - Benchmarks and optimization tips
+- [Security](security.md) - Security considerations and best practices
+- [Use Cases](use-cases.md) - Real-world examples and applications
+- [API Reference](api-reference.md) - Complete API documentation
+- [Development](development.md) - Contributing and development setup
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+This project follows an "open source, closed contribution" model. We welcome bug reports, feature requests, and documentation improvements through GitHub Issues.
+
+## Acknowledgements
+
+- [nanoid.rb](https://github.com/radeno/nanoid.rb) - Original inspiration and reference implementation
+- [NanoID](https://github.com/ai/nanoid) - The original JavaScript implementation
+- [PlanetScale Article](https://planetscale.com/blog/why-we-chose-nanoids-for-planetscales-api) by Mike Coutermarsh - Excellent explanation of opaque ID benefits