schema-model 0.6.10 → 0.7.0

data/README.md

@@ -1,163 +1,465 @@
-# schema
+# Schema
 
-Fast and easy way to transform data into models for validation and type safety.
+A powerful Ruby gem for data transformation, validation, and type safety. Schema provides a flexible and intuitive way to define data models with support for complex nested structures, dynamic associations, and robust validation.
 
-[![Build Status](https://travis-ci.org/dougyouch/schema.svg?branch=master)](https://travis-ci.org/dougyouch/schema)
-[![Maintainability](https://api.codeclimate.com/v1/badges/c142d46a7a37d4a8c2e5/maintainability)](https://codeclimate.com/github/dougyouch/schema/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/c142d46a7a37d4a8c2e5/test_coverage)](https://codeclimate.com/github/dougyouch/schema/test_coverage)
+[![CI](https://github.com/dougyouch/schema/actions/workflows/ci.yml/badge.svg)](https://github.com/dougyouch/schema/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/dougyouch/schema/graph/badge.svg)](https://codecov.io/gh/dougyouch/schema)
 
-Attributes of a model have a name and type.  Any value passed in goes through a parser method.  If the value can not be parsed successfully the error is added to parsing_errors.
+## Installation
 
-Associations are nested schema models.  Each association can have its own set of attributes.
+Add this line to your application's Gemfile:
 
-Dynamic associations are useful when creating custom logic around schema validation.
+```ruby
+gem 'schema-model'
+```
 
-#### Example that show cases multiple features
+And then execute:
 
-###### spec/examples/company_schema.rb
-```ruby
-# frozen_string_literal: true
+```bash
+$ bundle install
+```
 
-# Example that show cases multiple features
-class CompanySchema
-  # includes model, associations, parsers and active model validations
+## Quick Start
+
+```ruby
+class UserSchema
   include Schema::All
 
-  # add common attributes
-  # attributes support additional names through the alias(es) option
-  attribute :name, :string, alias: 'CompanyName'
-  attribute :industry_type, :string, aliases: %w[IndustryType industry]
+  attribute :name, :string
+  attribute :age, :integer
+  attribute :email, :string
+  attribute :active, :boolean, default: false
+  attribute :tags, :array, separator: ',', data_type: :string
 
-  # will take a string split on the separator and use the parse_<data_type> method on every element
-  # basically take a list of comma separated numbers and create an array of integers
-  # code snippet: str.split(',').map { |v| parse_integer(field_name, parsing_errors, v) }
-  attribute :number_list, :array, separator: ',', data_type: :integer
+  validates :name, presence: true
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+end
 
-  # creates a nested dynamic schema based on the industry_type which is part of the main company data
-  industry_schema = has_one(:industry, external_type_field: :industry_type) do
-    attribute :name, :string
+user = UserSchema.from_hash(
+  name: 'John Doe',
+  age: '30',
+  email: 'john@example.com',
+  active: 'yes',
+  tags: 'ruby,rails,developer'
+)
 
-    validates :name, presence: true
+user.valid?        # => true
+user.name          # => "John Doe"
+user.age           # => 30 (parsed to integer)
+user.active        # => true (parsed from "yes")
+user.tags          # => ["ruby", "rails", "developer"]
+```
 
-    add_type('tech') do
-      attribute :custom_description, :string
-    end
+## Data Types
 
-    add_type('qsr') do
-      attribute :number_of_locations, :integer
+### Basic Types
 
-      # custom validation
-      validates :number_of_locations, presence: true
-    end
+```ruby
+attribute :name, :string              # String values
+attribute :count, :integer            # Integer values (parses "123" to 123)
+attribute :price, :float              # Float values (parses "9.99" to 9.99)
+attribute :active, :boolean           # Boolean (accepts: 1, t, true, on, y, yes)
+attribute :notes, :string_or_nil      # String, but returns nil if empty
+```
+
+### Date and Time Types
+
+```ruby
+attribute :created_at, :time          # ISO 8601 format (Time.xmlschema)
+attribute :birth_date, :date          # Date.parse format
+attribute :us_date, :american_date    # MM/DD/YYYY format
+attribute :us_time, :american_time    # MM/DD/YYYY HH:MM:SS format
+```
+
+### Complex Types
+
+```ruby
+attribute :tags, :array                           # Array of values
+attribute :tags, :array, separator: ','           # Parse "a,b,c" into ["a","b","c"]
+attribute :tags, :array, separator: ',', data_type: :integer  # Parse and convert elements
+attribute :metadata, :hash                        # Hash/dictionary values
+attribute :config, :json                          # Parse JSON strings
+```
+
+## Attribute Options
+
+### Aliases
+
+```ruby
+# Single alias
+attribute :name, :string, alias: 'FullName'
+
+# Multiple aliases
+attribute :name, :string, aliases: [:full_name, :display_name]
+```
+
+### Default Values
+
+```ruby
+attribute :status, :string, default: 'pending'
+attribute :count, :integer, default: 0
+attribute :tags, :array, default: []
+```
+
+### Checking If Attribute Was Set
+
+Every attribute generates a `_was_set?` predicate method:
+
+```ruby
+user = UserSchema.from_hash(name: 'John')
+user.name_was_set?   # => true
+user.email_was_set?  # => false (not provided)
+
+# Useful for distinguishing "not provided" vs "provided as nil"
+user = UserSchema.from_hash(name: nil)
+user.name_was_set?   # => true (explicitly set to nil)
+```
+
+## Associations
+
+### Has One
+
+```ruby
+class OrderSchema
+  include Schema::All
+
+  attribute :id, :integer
+
+  has_one :customer do
+    attribute :name, :string
+    attribute :email, :string
   end
+end
 
-  # create multiple dynamic location schemas based on the type field in the location data
-  has_many(:locations, type_field: :type) do
-    attribute :type, :string
-    attribute :address, :string
-    attribute :city, :string
-    attribute :state, :string
-    attribute :zip, :string
+order = OrderSchema.from_hash(
+  id: 1,
+  customer: { name: 'Alice', email: 'alice@example.com' }
+)
+order.customer.name  # => "Alice"
+```
 
-    add_type('headquarters') do
-      attribute :main_floor, :integer
+### Has Many
 
-      validates :city, presence: true
-      validates :main_floor, presence: true
-    end
+```ruby
+class OrderSchema
+  include Schema::All
 
-    add_type('store_front') do
-      attribute :main_entrance, :string
+  attribute :id, :integer
 
-      validates :address, presence: true
-      validates :main_entrance, presence: true
-    end
+  has_many :items do
+    attribute :sku, :string
+    attribute :quantity, :integer
   end
+end
+
+order = OrderSchema.from_hash(
+  id: 1,
+  items: [
+    { sku: 'ABC', quantity: 2 },
+    { sku: 'XYZ', quantity: 1 }
+  ]
+)
+order.items.length       # => 2
+order.items.first.sku    # => "ABC"
+```
+
+### Association Options
+
+```ruby
+# Default values - creates empty model/array if not provided
+has_one :profile, default: true
+has_many :tags, default: true
+
+# Reuse existing schema class
+has_one :shipping_address, base_class: AddressSchema
+has_one :billing_address, base_class: AddressSchema
+
+# Has many from hash (keyed by field)
+has_many :items, from: :hash, hash_key_field: :id do
+  attribute :id, :string
+  attribute :name, :string
+end
+
+# Input: { items: { 'abc' => { name: 'Item 1' }, 'xyz' => { name: 'Item 2' } } }
+# Result: items[0].id => 'abc', items[1].id => 'xyz'
+```
+
+### Appending to Has Many
+
+```ruby
+order = OrderSchema.from_hash(id: 1, items: [])
+order.append_to_items(sku: 'NEW', quantity: 5)
+order.items.length  # => 1
+```
 
-  # create multiple dynamic employee schemas based on the type field in the employee data
-  has_many(:employees, type_field: :type) do
-    attribute :type, :integer
+## Dynamic Types
+
+Create different model structures based on a type field:
+
+```ruby
+class CompanySchema
+  include Schema::All
+
+  has_many :employees, type_field: :type do
+    attribute :type, :string
     attribute :name, :string
-    attribute :start_date, :date
-    add_type(1) do # worker
-      attribute :manager_name, :string
+
+    add_type('engineer') do
+      attribute :programming_languages, :array, separator: ','
     end
-    add_type(2) do # manager
-      attribute :rank, :float
+
+    add_type('manager') do
+      attribute :department, :string
+      attribute :team_size, :integer
     end
-    # if no or an invalid type is specified, create a default employee schema object
-    # useful for communicating errors in an API
-    default_type
 
-    # dynamic_type_names returns all the types used, except for :default
-    validates :type, inclusion: { in: dynamic_type_names }
+    default_type do
+      # Fallback for unknown types
+    end
   end
+end
 
-  has_many(:admins, from: :hash, hash_key_field: :username) do
-    attribute :username, :string
-    attribute :email, :string
-    attribute :name, :string
+company = CompanySchema.from_hash(
+  employees: [
+    { type: 'engineer', name: 'Alice', programming_languages: 'ruby,python' },
+    { type: 'manager', name: 'Bob', department: 'Engineering', team_size: 5 }
+  ]
+)
 
-    validates :username, presence: true
-    validates :email, presence: true
-  end
+company.employees[0].programming_languages  # => ["ruby", "python"]
+company.employees[1].team_size              # => 5
+```
+
+### Dynamic Type Options
+
+```ruby
+# Type field within nested data (default)
+has_many :items, type_field: :kind do
+  # looks for :kind in each item's data
+end
+
+# Type determined by parent field
+has_one :details, external_type_field: :category do
+  # uses parent's :category field to determine type
+end
+
+# Case-insensitive type matching
+has_many :items, type_field: :type, type_ignorecase: true do
+  add_type('widget') { }  # matches "Widget", "WIDGET", etc.
+end
+```
+
+## Validation and Error Handling
+
+### ActiveModel Validations
+
+```ruby
+class UserSchema
+  include Schema::All
+
+  attribute :name, :string
+  attribute :email, :string
+  attribute :age, :integer
 
   validates :name, presence: true
-  validates :industry_type, inclusion: { in: industry_schema.dynamic_type_names }
+  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :age, numericality: { greater_than: 0 }, allow_nil: true
+end
+```
+
+### Parsing Errors vs Validation Errors
+
+```ruby
+user = UserSchema.from_hash(name: 'John', age: 'not-a-number')
 
-  # use the schema validator
-  validates :industry, presence: true, schema: true
-  validates :locations, presence: true, schema: true
-  validates :employees, presence: true, schema: true
-  validates :admins, presence: true, schema: true
+# Parsing errors (type conversion failures)
+user.parsing_errors.empty?  # => false
+user.parsed?                # => false
+
+# Validation errors (business rules)
+user.valid?                 # => false (also runs validations)
+user.errors.full_messages   # => ["Age is invalid", ...]
+```
+
+### Raising Exceptions
+
+```ruby
+user = UserSchema.from_hash(age: 'invalid')
+
+user.parsed!      # raises Schema::ParsingException if parsing errors
+user.valid_model! # raises Schema::ValidationException if validation errors
+user.valid!       # raises either (checks both)
+
+# Exception includes the model and errors
+begin
+  user.valid!
+rescue Schema::ParsingException => e
+  e.schema  # => the model instance
+  e.errors  # => the errors object
 end
 ```
 
-###### spec/examples/company_schema.json
-```javascript
-{
-  "CompanyName": "Good Burger",
-  "IndustryType": "qsr",
-  "industry": {
-    "name": "Food & Beverage",
-    "number_of_locations": 2
-  },
-  "locations": [
-    {
-      "type": "headquarters",
-      "city": "Boston",
-      "main_floor": 5
-    },
-    {
-      "type": "store_front",
-      "address": "1st Ave",
-      "zip": "02211",
-      "main_entrance": "side door"
-    }
-  ],
-  "employees": [
-    {
-      "type": 2,
-      "name": "Queen Bee",
-      "start_date": "2016-01-09",
-      "rank": "0.9"
-    },
-    {
-      "type": 1,
-      "name": "Worker Bee",
-      "start_date": "2018-05-10",
-      "manager_name": "Queen Bee"
-    }
-  ],
-  "admins": {
-    "captain": {
-      "email": "captain@example.com",
-      "name": "Captain Kurk"
-    },
-    "joe": {
-      "email": "joe.smith@example.com",
-      "name": "Joe Smith"
-    }
-  }
+### Unknown Attributes
+
+By default, unknown attributes are captured as parsing errors:
+
+```ruby
+user = UserSchema.from_hash(name: 'John', unknown_field: 'value')
+user.parsing_errors[:unknown_field]  # => ["unknown_attribute"]
+
+# Disable this behavior
+UserSchema.capture_unknown_attributes = false
+```
+
+## Serialization
+
+### to_hash / as_json
+
+```ruby
+user = UserSchema.from_hash(name: 'John', email: nil)
+
+user.to_hash                          # => { name: "John", email: nil }
+user.as_json                          # => { name: "John" } (excludes nils)
+user.as_json(include_nils: true)      # => { name: "John", email: nil }
+
+# Filter fields
+user.as_json(select_filter: ->(name, value, opts) { name == :name })
+user.as_json(reject_filter: ->(name, value, opts) { value.nil? })
+```
+
+## Protecting Fields with skip_fields
+
+Prevent certain fields from being set by user input:
+
+```ruby
+user_data = {
+  id: 123,
+  name: 'John Doe',
+  created_at: '2024-01-01'
 }
+
+# Skip database-managed fields
+user = UserSchema.from_hash(user_data, [:id, :created_at])
+
+user.id          # => nil (not set)
+user.name        # => "John Doe"
+user.created_at  # => nil (not set)
+
+# Nested skip_fields for associations
+order = OrderSchema.from_hash(data, [:id, { items: [:id] }])
+```
+
+## Array and CSV Support
+
+### Schema::Arrays Module
+
+Convert models to/from flat arrays (useful for CSV/spreadsheet data):
+
+```ruby
+class UserSchema
+  include Schema::All
+  schema_include Schema::Arrays
+
+  attribute :name, :string
+  attribute :email, :string
+end
+
+# Get headers
+UserSchema.to_headers  # => ["name", "email"]
+
+# Convert to array
+user = UserSchema.from_hash(name: 'John', email: 'john@example.com')
+user.to_a  # => ["John", "john@example.com"]
+
+# Create from array
+headers = ['name', 'email']
+mapped = UserSchema.map_headers_to_attributes(headers)
+user = UserSchema.from_array(['Jane', 'jane@example.com'], mapped)
+```
+
+### Schema::CSVParser Module
+
+Parse CSV data directly into models:
+
+```ruby
+class UserCSVSchema
+  include Schema::Model
+  include Schema::CSVParser
+
+  attribute :name, :string
+  attribute :email, :string
+end
+
+csv_data = CSV.parse("name,email\nJohn,john@example.com", headers: true)
+parser = Schema::CSVParser.new(csv_data, UserCSVSchema)
+
+parser.each do |user|
+  puts user.name
+end
+```
+
+### Schema::ArrayHeaders Module
+
+Map CSV/array headers to schema attributes:
+
+```ruby
+class UserSchema
+  include Schema::All
+  schema_include Schema::ArrayHeaders
+
+  attribute :name, :string, alias: 'FullName'
+  attribute :email, :string
+end
+
+headers = ['FullName', 'email', 'unknown_column']
+mapped = UserSchema.map_headers_to_attributes(headers)
+# => { name: { index: 0 }, email: { index: 1 } }
+
+UserSchema.get_mapped_field_names(mapped)    # => ["name", "email"]
+UserSchema.get_unmapped_field_names(mapped)  # => []
 ```
+
+## Extending Schemas
+
+### schema_include
+
+Add modules to a schema and all its nested associations:
+
+```ruby
+class OrderSchema
+  include Schema::All
+
+  has_many :items do
+    attribute :name, :string
+  end
+end
+
+# Add Arrays support to OrderSchema and OrderSchema::SchemaHasManyItems
+OrderSchema.schema_include Schema::Arrays
+```
+
+## CLI Tools
+
+### schema-json2csv
+
+Convert JSON data to CSV using a schema:
+
+```bash
+# Basic usage
+schema-json2csv --require ./my_schema.rb --schema MySchema --json data.json --csv output.csv
+
+# From stdin
+cat data.json | schema-json2csv --require ./my_schema.rb --schema MySchema - --csv output.csv
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/schema/active_model_validations.rb

@@ -11,13 +11,13 @@ module Schema
     end
 
     def valid_model!
-      unless valid?
-        raise ValidationException.new(
-                "invalid values for attributes #{errors.map(&:attribute).join(', ')}",
-                self,
-                errors
-              )
-      end
+      return if valid?
+
+      raise ValidationException.new(
+        "invalid values for attributes #{errors.map(&:attribute).join(', ')}",
+        self,
+        errors
+      )
     end
 
     def valid!
@@ -36,13 +36,13 @@ module Schema
       end
 
       def parsed!
-        unless parsed?
-          raise ParsingException.new(
-                  "schema parsing failed for attributes #{parsing_errors.errors.map(&:attribute).join(', ')}",
-                  self,
-                  parsing_errors
-                )
-        end
+        return if parsed?
+
+        raise ParsingException.new(
+          "schema parsing failed for attributes #{parsing_errors.errors.map(&:attribute).join(', ')}",
+          self,
+          parsing_errors
+        )
       end
     end
   end

data/lib/schema/array_headers.rb

@@ -41,13 +41,15 @@ module Schema
         fields
       end
 
+      MAX_ARRAY_INDEX = 10_000
+
       private
 
       def get_model_field_names(field_name, field_options, mapped_headers, header_prefix, mapped)
         mapped_model = mapped_headers[field_name] || {}
         const_get(field_options[:class_name]).get_field_names(
           mapped_model,
-          header_prefix || (field_options[:aliases] && field_options[:aliases].first),
+          header_prefix || field_options[:aliases]&.first,
           mapped
         )
       end
@@ -62,7 +64,7 @@ module Schema
 
       def generate_field_name(field_name, field_options, header_prefix)
         field_name = field_options[:aliases].first if field_options[:aliases]
-        field_name = header_prefix + 'X' + field_name.to_s if header_prefix
+        field_name = "#{header_prefix}X#{field_name}" if header_prefix
         field_name.to_s
       end
 
@@ -114,9 +116,9 @@ module Schema
         cnt = field_options[:starting_index] || 1
         indexes = []
         # finding all headers that look like Company1Name through CompanyXName
-        while (index = headers.index(header_prefix + cnt.to_s + field_options[:key]))
-          cnt += 1
+        while cnt <= MAX_ARRAY_INDEX && (index = headers.index(header_prefix + cnt.to_s + field_options[:key]))
           indexes << index
+          cnt += 1
         end
         indexes
       end