validrb 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fb818549e6bca37a89242aee2e72b9f74c32cbafa3db4bb6cbaad060b93fc426
+  data.tar.gz: 0d7debd6603cbf1afb0bf664e1a3252de6c270bd2844ea8f2cd1406b198e4008
+SHA512:
+  metadata.gz: 33da9e6eefcc7c7b4ab78d8785c7b12b0216f8f0677b4d7120ebec5056ba1b6a42030afa3c13618c03d4e22e47538da085bc0783db7973698dcec6d2b44fea20
+  data.tar.gz: 2845fbd1a754e91509692d671d5ff050e738cc8799625d34028acc77cf47a041861f80556b23cefb05206c58b56350c62643d540b2ad6e51d5cc2644fea1ce16

data/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] - 2024-01-15
+
+### Added
+- **OpenAPI 3.0 Generation** - Generate complete OpenAPI specs from schemas
+- **OpenAPI Import** - Create Validrb schemas from OpenAPI/JSON Schema definitions
+- `Validrb::OpenAPI::Generator` for building OpenAPI documents
+- `Validrb::OpenAPI::PathBuilder` for defining API endpoints
+- `Validrb::OpenAPI::Importer` for importing external schemas
+- `Schema#to_openapi` method for single schema export
+- Support for servers, paths, and component schemas in OpenAPI output
+- JSON and YAML export formats
+
+### Production Readiness
+- Comprehensive README documentation
+- CHANGELOG following Keep a Changelog format
+- GitHub Actions CI workflow for Ruby 3.0-3.3
+- Updated gemspec with full metadata
+
+## [0.4.0] - 2024-01-15
+
+### Added
+- **Literal types** - Exact value matching with `literal:` option
+- **Refinements** - Custom validation predicates with `refine:` option
+- **Validation context** - Pass request-level data through validation pipeline
+- **Schema introspection** - `field_names`, `required_fields`, `optional_fields`, `to_schema_hash`
+- **JSON Schema generation** - `to_json_schema` method for JSON Schema Draft-07 output
+- **Custom type API** - `Validrb.define_type` DSL for creating custom types
+- **Discriminated unions** - Schema selection based on discriminator field
+- **Serialization** - `dump` and `to_json` methods for converting data to primitives
+- Context support in transforms, preprocessors, refinements, and validators
+
+### Changed
+- Field validation now accepts optional `context:` parameter
+- Schema `safe_parse` and `parse` now accept optional `context:` parameter
+- Validators can now receive context as second argument
+
+## [0.3.0] - 2024-01-14
+
+### Added
+- **Preprocessing** - `preprocess:` option for transforming input before validation
+- **Conditional validation** - `when:` and `unless:` options for conditional field validation
+- **Union types** - Accept multiple types with `union:` option
+- **Coercion modes** - Disable coercion per-field with `coerce: false`
+- **I18n support** - Internationalized error messages with locale switching
+- `Validrb::I18n` module with `add_translations`, `locale`, and `reset!`
+
+### Changed
+- Validation pipeline now: preprocess -> coerce -> constraints -> transform
+- Conditional fields are skipped when condition is false (treated as optional)
+
+## [0.2.0] - 2024-01-13
+
+### Added
+- **Custom validators** - Cross-field validation with `validate` blocks
+- **Custom error messages** - `message:` option for fields
+- **Date/DateTime/Time types** - Full temporal type support with coercion
+- **Decimal type** - BigDecimal support for precise numeric values
+- **Schema composition** - `extend`, `merge`, `pick`, `omit`, `partial` methods
+- **Unknown key handling** - `strict:` and `passthrough:` schema options
+- **Transforms** - `transform:` option for post-validation transformation
+- **Nullable fields** - `nullable:` option (distinct from `optional:`)
+- ValidatorContext class for custom validators with `error` and `base_error` methods
+
+### Changed
+- Schema now supports composition methods for building derived schemas
+- Error paths now support nested structures correctly
+
+## [0.1.0] - 2024-01-12
+
+### Added
+- Initial release
+- **Core types** - string, integer, float, boolean, array, object
+- **Type coercion** - Automatic conversion between compatible types
+- **Constraints** - min, max, length, format, enum
+- **Schema DSL** - `Validrb.schema` with `field` declarations
+- **Parsing methods** - `parse` (raises) and `safe_parse` (returns Result)
+- **Result types** - `Success` and `Failure` with data/errors
+- **Error tracking** - Path-tracked errors with ErrorCollection
+- **Named formats** - email, url, uuid, phone, alphanumeric, alpha, numeric, hex, slug
+- **Nested validation** - Objects and arrays with item/schema validation
+- **Field options** - optional, default, nullable
+- Zero runtime dependencies
+
+### Notes
+- Requires Ruby >= 3.0
+- Inspired by Pydantic (Python) and Zod (TypeScript)
+
+[0.5.0]: https://github.com/validrb/validrb/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/validrb/validrb/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/validrb/validrb/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/validrb/validrb/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/validrb/validrb/releases/tag/v0.1.0

data/CLAUDE.md

@@ -0,0 +1,434 @@
+# Validrb - Development Context
+
+## Project Overview
+
+Validrb is a Ruby schema validation library with type coercion, inspired by Pydantic (Python) and Zod (TypeScript). It provides a clean DSL for defining data schemas with automatic type coercion, constraint validation, and detailed error reporting.
+
+## Current Status: Phase 5 Complete
+
+All core functionality implemented and tested (719 tests passing).
+
+## Architecture
+
+```
+Validrb.schema { ... }
+       │
+       ▼
+    Schema (DSL, parse/safe_parse, composition, introspection)
+       │
+       ├── Validators (custom cross-field validation + context)
+       ├── Serialization (dump/to_json)
+       │
+       ▼
+    Field (preprocess → type → constraints → refinements → transform)
+       │
+       ├── Conditional (when:/unless: with context)
+       ├── Coercion modes (coerce: true/false)
+       ├── Literal types (exact value matching)
+       ├── Refinements (custom predicates)
+       │
+       ├──────────────┬──────────────┐
+       ▼              ▼              ▼
+    Types          Constraints    Context
+    (coerce→validate) (min/max/enum/format)  (request context)
+       │
+       ├── Union types
+       ├── Discriminated unions
+       ├── Custom types
+       │
+       ▼
+    Result (Success/Failure + serialization)
+    Errors (path-tracked, I18n)
+```
+
+## File Structure
+
+```
+lib/
+├── validrb.rb                    # Main entry point
+└── validrb/
+    ├── version.rb                # VERSION = "0.5.0"
+    ├── i18n.rb                   # I18n support for error messages
+    ├── errors.rb                 # Error, ErrorCollection, ValidationError
+    ├── result.rb                 # Success, Failure result types
+    ├── context.rb                # Validation context
+    ├── field.rb                  # Field definition with all options
+    ├── schema.rb                 # Schema class with DSL Builder + composition
+    ├── custom_type.rb            # Custom type DSL
+    ├── introspection.rb          # Schema/field introspection
+    ├── serializer.rb             # Serialization to primitives/JSON
+    ├── openapi.rb                # OpenAPI 3.0 generation and import
+    ├── types/
+    │   ├── base.rb               # Base type class + registry
+    │   ├── string.rb             # String type
+    │   ├── integer.rb            # Integer type
+    │   ├── float.rb              # Float type
+    │   ├── boolean.rb            # Boolean type
+    │   ├── array.rb              # Array type with item validation
+    │   ├── object.rb             # Object type for nested schemas
+    │   ├── date.rb               # Date type
+    │   ├── datetime.rb           # DateTime type
+    │   ├── time.rb               # Time type
+    │   ├── decimal.rb            # Decimal type (BigDecimal)
+    │   ├── union.rb              # Union type (multiple types)
+    │   ├── literal.rb            # Literal type (exact values)
+    │   └── discriminated_union.rb # Discriminated union type
+    └── constraints/
+        ├── base.rb               # Base constraint class + registry
+        ├── min.rb                # Minimum value/length
+        ├── max.rb                # Maximum value/length
+        ├── length.rb             # Exact/range/min/max length
+        ├── format.rb             # Regex or named formats
+        └── enum.rb               # Value in allowed list
+
+spec/
+├── spec_helper.rb
+├── validrb_spec.rb
+├── validrb/
+│   ├── errors_spec.rb
+│   ├── result_spec.rb
+│   ├── field_spec.rb
+│   ├── schema_spec.rb
+│   ├── i18n_spec.rb
+│   ├── context_spec.rb
+│   ├── custom_type_spec.rb
+│   ├── serializer_spec.rb
+│   ├── introspection_spec.rb
+│   ├── openapi_spec.rb
+│   ├── types/*.rb
+│   └── constraints/*.rb
+└── integration/
+    ├── basic_schema_spec.rb
+    ├── nested_schema_spec.rb
+    ├── phase2_features_spec.rb
+    ├── phase3_features_spec.rb
+    ├── phase4_features_spec.rb
+    └── phase4_edge_cases_spec.rb
+```
+
+## API Reference
+
+### Schema Definition
+
+```ruby
+schema = Validrb.schema do
+  # Basic fields
+  field :name, :string
+  field :age, :integer, optional: true
+  field :role, :string, default: "user"
+
+  # Constraints
+  field :email, :string, format: :email
+  field :bio, :string, min: 10, max: 500
+  field :status, :string, enum: %w[active inactive]
+
+  # Preprocessing (runs BEFORE validation)
+  field :username, :string, preprocess: ->(v) { v.strip.downcase }
+
+  # Transform (runs AFTER validation)
+  field :tags, :string, transform: ->(v) { v.split(",") }
+
+  # Nullable (accepts nil)
+  field :deleted_at, :datetime, nullable: true
+
+  # Union types (accepts multiple types)
+  field :id, :string, union: [:integer, :string]
+
+  # Literal types (exact values only)
+  field :priority, :integer, literal: [1, 2, 3]
+
+  # Refinements (custom predicates)
+  field :password, :string,
+        refine: [
+          { check: ->(v) { v.length >= 8 }, message: "must be 8+ chars" },
+          { check: ->(v) { v.match?(/\d/) }, message: "must contain digit" }
+        ]
+
+  # Context-aware refinement
+  field :amount, :decimal,
+        refine: ->(v, ctx) { ctx.nil? || v <= ctx[:max_amount] }
+
+  # Disable coercion
+  field :count, :integer, coerce: false
+
+  # Conditional validation (supports context)
+  field :company, :string, when: ->(d, ctx) { d[:account_type] == "business" }
+  field :personal_id, :string, unless: :is_company
+
+  # Custom error message
+  field :note, :string, min: 8, message: "must be at least 8 characters"
+
+  # Nested schema
+  field :address, :object, schema: AddressSchema
+
+  # Typed arrays
+  field :scores, :array, of: :integer
+
+  # Discriminated union
+  field :payment, :discriminated_union,
+        discriminator: :method,
+        mapping: { "card" => CardSchema, "paypal" => PaypalSchema }
+
+  # Custom validators (support context)
+  validate do |data, ctx|
+    if ctx && ctx[:restricted] && data[:amount] > 100
+      error(:amount, "exceeds limit in restricted mode")
+    end
+  end
+end
+```
+
+### Schema Options
+
+```ruby
+# Strict mode - reject unknown keys
+Validrb.schema(strict: true) { ... }
+
+# Passthrough mode - keep unknown keys
+Validrb.schema(passthrough: true) { ... }
+```
+
+### Field Options Reference
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `optional` | Boolean | Field can be missing (default: false) |
+| `nullable` | Boolean | Field accepts nil value (default: false) |
+| `default` | Any/Proc | Default value when missing |
+| `message` | String | Custom error message |
+| `preprocess` | Proc | Transform input BEFORE validation |
+| `transform` | Proc | Transform value AFTER validation |
+| `coerce` | Boolean | Enable type coercion (default: true) |
+| `when` | Proc/Symbol | Only validate if condition is true |
+| `unless` | Proc/Symbol | Only validate if condition is false |
+| `union` | Array | Accept any of these types |
+| `literal` | Array | Accept only these exact values |
+| `refine` | Proc/Array | Custom validation predicates |
+| `min` | Numeric | Minimum value/length |
+| `max` | Numeric | Maximum value/length |
+| `length` | Int/Range/Hash | Length constraint |
+| `format` | Symbol/Regexp | Format validation |
+| `enum` | Array | Allowed values |
+| `of` | Symbol | Item type for arrays |
+| `schema` | Schema | Nested schema for objects |
+| `discriminator` | Symbol | Field for discriminated union |
+| `mapping` | Hash | Schemas for discriminated union |
+
+### Type Coercion Rules
+
+| Type | Accepts | Coerces From |
+|------|---------|--------------|
+| `:string` | String | Symbol, Numeric |
+| `:integer` | Integer | String, Float (whole) |
+| `:float` | Float | String, Integer |
+| `:boolean` | true/false | "true"/"false", "yes"/"no", 1/0, etc. |
+| `:array` | Array | (validates items with `of:`) |
+| `:object` | Hash | (validates with `schema:`) |
+| `:date` | Date | ISO8601 String, Time, DateTime, timestamp |
+| `:datetime` | DateTime | ISO8601 String, Time, Date, timestamp |
+| `:time` | Time | ISO8601 String, DateTime, Date, timestamp |
+| `:decimal` | BigDecimal | String, Integer, Float, Rational |
+| `:union` | Any matching | Tries each type in order |
+| `:literal` | Exact value | No coercion, exact match only |
+| `:discriminated_union` | Object | Selects schema by discriminator field |
+
+### Named Formats
+
+`:email`, `:url`, `:uuid`, `:phone`, `:alphanumeric`, `:alpha`, `:numeric`, `:hex`, `:slug`
+
+### Schema Composition
+
+```ruby
+# Extend with additional fields
+UserSchema = BaseSchema.extend { field :name, :string }
+
+# Pick specific fields
+PublicSchema = FullSchema.pick(:id, :name)
+
+# Omit fields
+SafeSchema = FullSchema.omit(:password)
+
+# Merge schemas
+MergedSchema = Schema1.merge(Schema2)
+
+# Make all fields optional
+UpdateSchema = CreateSchema.partial
+```
+
+### I18n Configuration
+
+```ruby
+# Add custom translations
+Validrb::I18n.add_translations(:en, required: "cannot be blank")
+
+# Change locale
+Validrb::I18n.locale = :es
+
+# Add translations for other locales
+Validrb::I18n.add_translations(:es, required: "es requerido")
+
+# Use Rails I18n backend
+Validrb::I18n.backend = :rails
+```
+
+### Validation Context
+
+```ruby
+# Create a context
+ctx = Validrb.context(user_id: 123, is_admin: true, max_amount: 1000)
+
+# Pass context to parse
+result = schema.safe_parse(data, context: ctx)
+
+# Context is available in refinements, conditions, transforms, and validators
+field :amount, :decimal, refine: ->(v, ctx) { v <= ctx[:max_amount] }
+field :admin_only, :string, when: ->(data, ctx) { ctx[:is_admin] }
+```
+
+### Custom Types
+
+```ruby
+# Define a custom type
+Validrb.define_type(:money) do
+  coerce { |v| BigDecimal(v.to_s.gsub(/[$,]/, "")) }
+  validate { |v| v >= 0 }
+  error_message { "must be a valid money amount" }
+end
+
+# Use in schemas
+field :price, :money
+```
+
+### Schema Introspection
+
+```ruby
+# Field inspection
+schema.field_names          # => [:id, :name, :email]
+schema.required_fields      # => [:id, :name]
+schema.optional_fields      # => [:age]
+schema.fields_with_defaults # => [:role]
+schema.conditional_fields   # => [:company]
+
+# Field details
+field = schema.field(:name)
+field.constraint_values     # => { min: 1, max: 100 }
+field.has_constraint?(Validrb::Constraints::Min) # => true
+
+# Generate JSON Schema
+schema.to_json_schema       # => { "$schema": "...", "type": "object", ... }
+```
+
+### Serialization
+
+```ruby
+# Parse and serialize to hash with primitives
+result = schema.safe_parse(data)
+result.dump                  # => { "name" => "John", "date" => "2024-01-15" }
+result.dump(format: :json)   # => '{"name":"John","date":"2024-01-15"}'
+result.to_json               # Same as dump(format: :json)
+
+# Schema-level serialization
+schema.dump(data)            # Parse + serialize (raises on error)
+schema.safe_dump(data)       # Parse + serialize (returns Result)
+```
+
+### Validation Flow
+
+```
+Input Value
+    │
+    ▼
+┌─────────────────┐
+│ Conditional?    │──No──┐
+│ (when:/unless:) │      │
+└────────┬────────┘      │
+         │Yes            │
+         ▼               │
+┌─────────────────┐      │
+│ Should validate?│──No──┼──► Skip (return nil)
+└────────┬────────┘      │
+         │Yes            │
+         ▼               │
+┌─────────────────┐      │
+│ Preprocess      │◄─────┘
+│ (before coerce) │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Type Coercion   │──► coerce: false? → Type Check Only
+│ (if enabled)    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Constraints     │
+│ (min/max/etc)   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Transform       │
+│ (after valid)   │
+└────────┬────────┘
+         │
+         ▼
+    Output Value
+```
+
+## Running Tests
+
+```bash
+bundle install
+bundle exec rspec              # Run all tests
+bundle exec rspec --format doc # Verbose output
+```
+
+## Version History
+
+### Phase 1 (v0.1.0)
+- Basic types (string, integer, float, boolean, array, object)
+- Constraints (min, max, length, format, enum)
+- Schema DSL, type coercion, nested validation
+- Error path tracking, parse/safe_parse
+
+### Phase 2 (v0.2.0)
+- Custom validators (cross-field validation)
+- Custom error messages
+- Date/DateTime/Time types
+- Decimal type (BigDecimal)
+- Schema composition (extend, merge, pick, omit, partial)
+- Unknown keys handling (strict/passthrough)
+- Transforms (post-validation)
+- Nullable fields
+
+### Phase 3 (v0.3.0)
+- Preprocessing (pre-validation transformation)
+- Conditional validation (when:/unless:)
+- Union types (multiple type acceptance)
+- Coercion modes (disable per-field)
+- I18n support (internationalized errors)
+
+### Phase 4 (v0.4.0)
+- Literal types (exact value matching)
+- Refinements (custom validation predicates)
+- Validation context (request-level data)
+- Schema introspection (field inspection, JSON Schema generation)
+- Custom type API (define_type DSL)
+- Discriminated unions (type selection by discriminator)
+- Serialization (dump to primitives/JSON)
+
+## Future Enhancements
+
+- [ ] Async validators (database checks)
+- [ ] Rails integration (ActiveModel compatibility)
+- [ ] OpenAPI schema generation
+- [ ] Dependent field validation DSL
+
+## Code Conventions
+
+- All files use `# frozen_string_literal: true`
+- Zero runtime dependencies (bigdecimal is stdlib)
+- Ruby >= 3.0 required
+- RSpec for testing
+- Objects are frozen/immutable after creation

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Validrb Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.