dami 1.0.0

data/docs/04.Creating_Updating_Deleting.md

@@ -0,0 +1,226 @@
+# Chapter 4: Creating, Updating, and Deleting
+
+This chapter covers all operations that modify data in your database. Dami provides a simple yet secure API for creating, updating, and deleting records, with built-in protections against common vulnerabilities.
+
+## Creating Records
+
+### Creating a Single Record
+
+The most common way to insert a new record is with the `.create` method. It accepts a hash of attributes and, if successful, returns a `RecordProxy` instance of the newly created record.
+
+```ruby
+# Create a new user
+new_user = Dami.db(:users).create(
+  name: 'Carol',
+  email: 'carol@example.com',
+  status: 'active'
+)
+
+puts new_user[:id]    # => 43
+puts new_user[:name]  # => "Carol"
+```
+
+If the data fails validation, `.create` will raise a `Dami::ValidationError` instead of creating the record.
+
+### Creating Multiple Records (Bulk Inserts) ✨
+
+For inserting multiple records at once, always use `.create_many`. It is significantly more performant as it inserts all records with a single SQL statement. It accepts an array of hashes.
+
+```ruby
+# Create two new posts in a single database query
+posts_to_create = [
+  { user_id: 1, title: 'My First Post' },
+  { user_id: 1, title: 'My Second Post' }
+]
+
+Dami.db(:posts).create_many(posts_to_create)
+```
+
+## Updating Records
+
+The `.update` method is called on a query chain and modifies all records that match the preceding `where` conditions. It returns the first matching record (re-read after the update), so for multi-record updates treat the return value as a sample, not a summary. Validations run against the attributes you pass; conditional rules (`if:` / `unless:` / `when:`) see the first matching record as context.
+
+### Updating a Single Record
+
+The most common pattern is to find a record by its ID and then update it.
+
+```ruby
+# Find user with ID 1 and update their name
+Dami.db(:users).where(id: 1).update(name: 'Alice Smith')
+
+# You can also update multiple attributes at once
+Dami.db(:users).where(id: 1).update(
+  name: 'Alice Smith',
+  email: 'alicesmith@example.com'
+)
+```
+
+### Updating Multiple Records
+
+You can efficiently update many records that match a condition in a single query.
+
+```ruby
+# Promote all 'pending' users to 'active'
+Dami.db(:users).where(status: 'pending').update(status: 'active')
+
+# Archive all posts older than one year
+Dami.db(:posts)
+  .where('published_at < ?', 1.year.ago)
+  .update(status: 'archived')
+```
+
+## Deleting Records
+
+Similar to `update`, the `.delete` method is called on a query chain and removes all records that match the conditions.
+
+### Deleting a Single Record
+
+```ruby
+# Delete the user with ID 42
+Dami.db(:users).where(id: 42).delete
+```
+
+### Deleting Multiple Records
+
+```ruby
+# Clean up all spam comments in one query
+Dami.db(:comments).where(is_spam: true).delete
+
+# Delete all posts by a specific user
+Dami.db(:posts).where(user_id: 15).delete
+```
+
+## Security: Attribute Protection 🛡️
+
+A critical feature of any ORM is protection against **mass-assignment vulnerabilities**. This happens when a user submits extra data in a form (e.g., `role: 'admin'`) and the application blindly saves it.
+
+Dami protects you by default. You must explicitly define which attributes are sensitive using a `protection` block in your model.
+
+```ruby
+# In your behavior definition
+Dami.behavrior :users do
+  # ... fields ...
+  protection do
+    protect :role, :account_balance # These fields cannot be changed by default
+  end
+end
+
+# An attacker tries to make themselves an admin
+malicious_params = { name: 'Eve', email: 'eve@hacker.com', role: 'admin' }
+
+# This will fail with an error!
+Dami.db(:users).where(id: 10).update(malicious_params)
+# => raises Dami::ProtectionError: Protected fields not permitted: role
+```
+
+To safely update protected attributes in controlled parts of your code (like an admin panel), you must use the `permit:` option.
+
+```ruby
+# In an admin controller, you can safely permit the role change.
+admin_params = { role: 'moderator' }
+Dami.db(:users).where(id: 10).update(admin_params, permit: [:role]) # This now works
+```
+
+⚠️ For rare cases where you need to bypass all protections, you can use `protect: false`. Use this with extreme caution.
+
+```ruby
+# Disables all protections for this single operation
+Dami.db(:users).create(name: 'Root', role: 'super_admin', protect: false)
+```
+
+## Handling Validations
+
+If `create` or `update` is called with data that violates a model's validation rules, a `Dami::ValidationError` is raised. You can rescue this error to handle the failure gracefully, for example, by re-rendering a form with error messages.
+
+```ruby
+begin
+  # Attempt to create a user with a missing name
+  user_params = { email: 'test@example.com', status: 'active' }
+  Dami.db(:users).create(user_params)
+rescue Dami::ValidationError => e
+  # The operation failed, and e.errors contains the details
+  puts e.errors # => { name: ["is required"] }
+  
+  # You can now use this hash to display errors to the user
+  render_form_with_errors(e.errors)
+end
+```
+
+## Nested Attributes
+
+Dami provides a powerful way to create, update, and destroy associated records through a parent record in a single, atomic operation. This is particularly useful for complex forms where a user might edit a blog post and its comments at the same time.
+
+
+### Enabling Nested Attributes
+
+To enable this feature, you must explicitly declare it on the parent model using the `nests` keyword. This is a security measure to prevent accidental modification of associations.
+
+```ruby
+Dami.model :posts do
+  fields { field :title, :string }
+  relationships { has_many :comments }
+
+  # Enable nested attributes for the :comments association
+  nests :comments, allow_destroy: true
+end
+
+Dami.model :comments do
+  fields { field :post_id, :integer; field :content, :text }
+  relationships { belongs_to :post }
+end
+````
+
+The `allow_destroy: true` option is required if you want to allow nested records to be deleted.
+
+### Usage
+
+You can now modify the parent and its children by passing a special `_attributes` key in your `create` or `update` call.
+
+#### **Creating Records**
+
+To create a parent with new children, provide an array of hashes.
+
+```ruby
+@db[:posts].create(
+  title: 'My New Post',
+  comments_attributes: [
+    { content: 'This is the first comment.' },
+    { content: 'And this is the second.' }
+  ]
+)
+```
+
+#### **Updating and Destroying Records**
+
+To update existing children or destroy them, you must provide their `id`. To mark a record for destruction, add a `_destroy: '1'` key.
+
+```ruby
+@post = @db[:posts].find(1)
+@comment_to_update = @post.comments.first
+@comment_to_destroy = @post.comments.last
+
+@db[:posts].where(id: @post[:id]).update(
+  title: 'An Updated Title',
+  comments_attributes: [
+    # To UPDATE, provide the ID
+    { id: @comment_to_update[:id], content: 'This comment has been edited.' },
+
+    # To CREATE, omit the ID
+    { content: 'This is a brand new comment.' },
+    
+    # To DESTROY, provide the ID and _destroy flag
+    { id: @comment_to_destroy[:id], _destroy: '1' }
+  ]
+)
+```
+
+### Key Guarantees
+
+  * **Atomicity**: The entire operation—saving the parent and all children—is wrapped in a single database transaction. If *any* part fails (e.g., a single child comment fails its validation), the **entire operation is rolled back**, and no records are saved or changed.
+  * **Validation**: All nested records are validated against their own model's rules. If any fail, a single `Dami::ValidationError` is raised with a nested hash of all errors from all records, perfect for displaying in a form.
+  * **Protection**: Nested records respect their own `protection` rules. You cannot change a protected attribute on a child model unless you use the `permit:` option on the top-level `update` call.
+
+## What's Next?
+
+  * **Chapter 5: Validation** - A deep dive into defining data quality rules.
+  * **Chapter 6: Protection** - Develop permit, protect, field-level security

data/docs/05.Validation.md

@@ -0,0 +1,259 @@
+# Chapter 5: Validation
+
+Validation is the cornerstone of data integrity. Dami provides a powerful and declarative DSL to ensure that only valid data is saved to your database. If a record fails its validation rules, Dami will raise a `Dami::ValidationError` and prevent the `create` or `update` operation from proceeding.
+
+**Validations live in `Dami.behavior`**, keeping write-side rules separate from structure.
+
+## Defining Validations
+
+Validations are defined within a `validate` block in your `Dami.behavior` block. You use the `rule` method to apply one or more validation rules to a field.
+
+```ruby
+Dami.model :users do
+  fields do
+    field :name, :string
+    field :email, :string
+    field :status, :string
+  end
+end
+
+Dami.behavior :users do
+  validate do
+    rule :name, :required
+    rule :email, :required, :email
+    rule :status, inclusion: %w[active inactive pending]
+  end
+end
+```
+
+---
+
+## Registering Validation Rules
+
+Before you can use validation rules, register them in your initializer:
+
+```ruby
+# config/initializers/dami.rb
+Dami.connect(:default, adapter: :sqlite, path: 'db.sqlite')
+Dami.register_default_rules!
+```
+
+This registers these common rules:
+
+| Rule          | Description                                        |
+|---------------|----------------------------------------------------|
+| `:required`, `:presence` | Ensures the value is not `nil` or an empty string. |
+| `:email`      | Checks for a valid email format.                   |
+| `:inclusion`  | Ensures the value is within the given list.        |
+| `:format`     | Checks that the value matches a regex.             |
+| `:min_length` | Ensures the string has at least N characters.      |
+| `:max_length` | Ensures the string has at most N characters.       |
+| `:min`        | Ensures the number is at least N.                  |
+| `:max`        | Ensures the number is at most N.                   |
+
+### Customizing Error Messages
+
+**Global Message Overrides:**
+
+Change error messages for all validations without modifying rules:
+
+```ruby
+# config/initializers/dami.rb
+Dami.register_default_rules!
+Dami.override_messages :default, {
+  required: "cannot be blank",
+  email: "must be a valid email address",
+  min_length: ->(min) { "too short (minimum: #{min} characters)" }
+}
+```
+
+Messages are checked in this priority order:
+1. Custom rule's message (when registering a new rule)
+2. Global override (via `override_messages`)
+3. Default message (from `register_default_rules!`)
+
+### Custom Validation Rules
+
+Register your own rules for domain-specific validations:
+
+```ruby
+Dami.rules :default, {
+  phone: { 
+    check: ->(v) { v.to_s =~ /\A\d{3}-\d{3}-\d{4}\z/ }, 
+    message: "must be a valid phone number (XXX-XXX-XXXX)" 
+  },
+  url: { 
+    check: ->(v) { v.to_s =~ /\Ahttps?:\/\// }, 
+    message: "must be a valid URL" 
+  }
+}
+```
+
+**Parameterized Rules:**
+
+For rules that take options, return a hash from a lambda:
+
+```ruby
+Dami.rules :default, {
+  exact_length: ->(len) { 
+    { 
+      check: ->(v) { v.to_s.length == len }, 
+      message: "must be exactly #{len} characters" 
+    } 
+  }
+}
+```
+
+```ruby
+# Usage
+Dami.behavior :users do
+  validate do
+    rule :zip_code, exact_length: 5
+  end
+end
+```
+
+---
+
+## Validating Multiple Fields
+
+The `all` helper applies the same rules to multiple fields at once:
+
+```ruby
+Dami.behavior :users do
+  validate do
+    # Apply :required to all fields except :age
+    on :create do
+      all except: [:age] do
+        rule :required
+      end
+    end
+  end
+end
+```
+
+**Options:**
+- `only: [:field1, :field2]` - Apply rules only to these fields
+- `except: [:field3]` - Apply rules to all fields except these
+- `**kwargs` - Apply rules directly: `all presence: true, min_length: 3`
+
+```ruby
+Dami.behavior :users do
+  validate do
+    # Apply presence validation to specific fields
+    all only: [:name, :email], presence: true
+    
+    # Apply multiple rules to all fields except one
+    all except: [:bio] do
+      rule :required
+      rule :min_length, 3
+    end
+  end
+end
+```
+
+---
+
+## Contextual Validation
+
+Sometimes a rule should only apply during a specific operation. You can scope rules to `:create` or `:update` using an `on` block.
+
+```ruby
+Dami.behavior :users do
+  validate do
+    rule :name, :required
+    
+    on :create do
+      rule :email, :required
+    end
+  end
+end
+```
+
+---
+
+## Conditional Validation
+
+For more complex logic, you can make a validation conditional based on the values of other attributes.
+
+### Using `if:` and `unless:`
+
+Use `if:` or `unless:` with a lambda (`->`) for dynamic conditions. The lambda receives a hash of all the attributes being updated.
+
+```ruby
+Dami.behavior :users do
+  validate do
+    rule :ssn, :required, if: ->(attrs) { attrs[:account_type] == 'business' }
+  end
+end
+```
+
+### Using `when:`
+
+For simple equality checks, `when:` provides a convenient shortcut. The rule only runs if the attributes in the `when` hash match the record's attributes.
+
+```ruby
+Dami.behavior :orders do
+  validate do
+    rule :shipping_address, :required, when: { delivery_type: 'physical' }
+  end
+end
+```
+
+---
+
+## Validating Virtual Fields
+
+A common use case for validation is to check fields that you don't actually save to the database, like a password confirmation. These are called **virtual fields**.
+
+```ruby
+Dami.model :users do
+  fields do
+    field :password_hash, :string
+  end
+  virtual do
+    field :password, :string
+    field :password_confirmation, :string
+  end
+end
+
+Dami.behavior :users do
+  validate do
+    rule :password, :required, min_length: 8
+    rule :password_confirmation do |confirmation, attrs|
+      confirmation == attrs[:password]
+    end
+  end
+end
+```
+
+In this example, `password` and `password_confirmation` are accepted as input and validated, but only the `password_hash` (which you would generate from the password) is saved to the database.
+
+---
+
+## Handling Errors
+
+When a validation fails, Dami raises a `Dami::ValidationError`. You can `rescue` this error to access a hash of all the validation failures.
+
+```ruby
+begin
+  Dami.db(:users).create(name: '', email: 'invalid-email')
+rescue Dami::ValidationError => e
+  puts e.message  # => "Validation failed"
+  
+  puts e.errors
+  # => {
+  #      :name=>["is required"],
+  #      :email=>["must be valid email"]
+  #    }
+end
+```
+
+This error hash is designed to be easily used to display feedback to a user in a web form or API response.
+
+---
+
+## What's Next?
+
+* **Chapter 6: Protection** - Learn how to secure your models from mass-assignment vulnerabilities
+* **Chapter 7: Associations** - Define and query relationships between your models

data/docs/06.Protection.md

@@ -0,0 +1,160 @@
+# Chapter 6: Protection
+
+Data security is not optional. A common web application vulnerability is **mass-assignment**, where a malicious user submits unexpected fields in a form—like `role: 'admin'`—and the application blindly saves them. Dami prevents this by default through a simple and powerful attribute protection system.
+
+**Protection rules live in `Dami.behavior`**, keeping security policies separate from structure.
+
+## The Problem: Mass-Assignment
+
+Imagine a user signs up with the following data:
+
+```ruby
+malicious_params = {
+  name: 'Eve',
+  email: 'eve@hacker.com',
+  role: 'admin' # Uh oh!
+}
+
+# If the app is not secure, this might create an admin user!
+Dami.db(:users).create(malicious_params)
+```
+
+Without protection, this simple action could grant unauthorized administrative access. Dami's protection layer is designed to stop this.
+
+---
+
+## Protecting Attributes
+
+You declare which attributes are sensitive using the `protect` method inside a `protection` block in your `Dami.behavior` block.
+
+```ruby
+Dami.model :users do
+  fields do
+    field :name, :string
+    field :email, :string
+    field :role, :string
+  end
+end
+
+Dami.behavior :users do
+  protection do
+    protect :role  # Cannot be mass-assigned
+  end
+end
+```
+
+Now, if someone attempts the same malicious action, Dami will raise an error and the operation will fail, keeping your application secure.
+
+```ruby
+malicious_params = { name: 'Eve', role: 'admin' }
+
+Dami.db(:users).create(malicious_params)
+# => raises Dami::ProtectionError: Protected fields not permitted: role
+```
+
+---
+
+## Permitting Attributes
+
+In addition to `protect`, you can use `permit` to explicitly allow certain fields. This is useful for fields that are safe for users to modify:
+
+```ruby
+Dami.behavior :users do
+  protection do
+    protect :role       # Always blocked
+    permit :status      # Always allowed
+  end
+end
+```
+
+```ruby
+# This works - status is permitted
+Dami.db(:users).create(name: 'Alice', status: 'active')
+
+# This fails - role is protected
+Dami.db(:users).create(name: 'Eve', role: 'admin')
+# => Dami::ProtectionError
+```
+
+---
+
+## Safely Updating Protected Fields
+
+There are legitimate times when you need to change a protected attribute, such as in an admin panel or a background job. To do this safely, you must explicitly grant permission for the operation using the `permit:` option.
+
+The `permit:` option takes an array of symbols representing the protected fields you are allowing to be changed for this **single operation**.
+
+```ruby
+# In an admin controller, an authorized user is changing another user's role
+user_id = 42
+update_params = { role: 'moderator' }
+
+# The permit option grants temporary permission
+Dami.db(:users)
+  .where(id: user_id)
+  .update(update_params, permit: [:role]) # ✅ This is safe and will succeed
+```
+
+This makes your security intentions explicit. You are telling Dami, "For this one call, I know what I'm doing and I am intentionally modifying a protected field."
+
+---
+
+## Bypassing All Protections (Use with Caution)
+
+In very rare circumstances, like in a seed script or a system migration, you may need to bypass all protections entirely. For this, you can use the `protect: false` option.
+
+⚠️ **This is the nuclear option.** It disables all `protect` rules for the operation. Use it with extreme care and never with parameters coming directly from a user.
+
+```ruby
+# Creating a system-level user during initial setup
+Dami.db(:users).create(
+  name: 'Root',
+  role: 'super_admin',
+  status: 'active',
+  protect: false # Disables all protections for this one call
+)
+```
+
+---
+
+## Protection in Batch Operations
+
+Protection is enforced in batch operations like `create_many`:
+
+```ruby
+Dami.behavior :users do
+  protection do
+    protect :role
+  end
+end
+
+# This will raise Dami::ProtectionError
+Dami.db(:users).create_many([
+  { name: 'Alice', role: 'admin' },
+  { name: 'Bob', role: 'admin' }
+])
+
+# To allow it, use permit:
+Dami.db(:users).create_many([
+  { name: 'Alice', role: 'admin' },
+  { name: 'Bob', role: 'admin' }
+], permit: [:role])
+```
+
+**Important:** `create_many` validates all records before any database writes. If any record fails protection or validation, the entire batch is rejected atomically.
+
+---
+
+## Best Practices
+
+* **Protect by Default**: Be aggressive with the `protect` rule. If an attribute should not be changed by a regular user, protect it. Common examples include `role`, `is_admin`, `account_balance`, `verified`
+* **Use `permit` for Safe Fields**: Explicitly mark fields that are always safe to modify, like `status` or user preferences
+* **Permit Explicitly in Code**: Use the `permit: [...]` option in the specific, secure parts of your code (like admin controllers or service objects) where you intend to modify sensitive data
+* **Avoid `protect: false`**: Reserve `protect: false` for trusted, internal scripts where you have full control over the input data
+
+---
+
+## What's Next?
+
+* **Chapter 7: Associations** - Learn how to define, query, and manage relationships between your models
+* **Chapter 8: Scopes** - Create reusable query shortcuts to keep your code clean and readable