u-attributes 3.0.2 → 3.1.0

data/README.md

@@ -13,60 +13,127 @@
   </p>
 </p>
 
-This gem allows you to define "immutable" objects, when using it your objects will only have getters and no setters.
-So, if you change [[1](#with_attribute)] [[2](#with_attributes)] an attribute of the object, you’ll have a new object instance. That is, you transform the object instead of modifying it.
+`u-attributes` lets you define classes whose instances expose attribute readers but no setters. Mutation goes through [`#with_attribute`](#with_attribute) / [`#with_attributes`](#with_attributes), which return a new instance — you transform the object instead of modifying it.
+
+## Why u-attributes? <!-- omit in toc -->
+
+- **Lighter than `ActiveModel::Attributes`** — no Rails dependency required; ActiveModel integration is opt-in.
+- **More than `Struct`** — defaults (including callable ones), required keys, value validation (`accept:` / `reject:`), per-attribute visibility, freezing, immutable updates, and deep composition.
+- **Opt-in surface** — start with `include Micro::Attributes`; layer `:diff`, `:accept`, `:initialize`, `:keys_as_symbol`, and ActiveModel validations only when needed.
+- **Composes recursively** — nested children via `accept:` or inline blocks; hashes auto-coerce, and validation errors bubble up the tree (see [Composition](#composition)).
+
+## Quick start <!-- omit in toc -->
+
+```ruby
+require 'u-attributes'
+
+class Person
+  include Micro::Attributes.with(:initialize)
+
+  attribute :name, default: 'Anonymous'
+  attribute :age,  required: true
+end
+
+person = Person.new(age: 21)
+person.name # "Anonymous"
+person.age  # 21
+
+older = person.with_attribute(:age, 22)
+older.age            # 22
+older.equal?(person) # false  — a new instance
+
+# There are no setters.
+person.name = 'X'    # NoMethodError
+```
+
+Prefer a one-liner? [`Micro::Attributes.new`](#microattributesnew) returns a fresh class with `:initialize` and `:accept` enabled by preset:
+
+```ruby
+Person = Micro::Attributes.new do
+  attribute :name, default: 'Anonymous'
+  attribute :age,  required: true
+end
+```
+
+Need nested attributes? Define them inline with a [block](#defining-nested-attributes-inline-block-form) — child blocks inherit the host's feature mix and [compose to any depth](#deep-nesting--validation-bubbling):
+
+```ruby
+Order = Micro::Attributes.new do
+  attribute :id, accept: Integer
+
+  attribute :customer do
+    attribute :name,  accept: String
+    attribute :email, accept: String
+  end
+end
+
+order = Order.new(id: 1, customer: { name: 'Rodrigo', email: 'rodrigo@example.com' })
+order.customer.name # "Rodrigo"
+```
+
+See [Feature overview](#feature-overview) for what else the gem can do.
 
 ## Documentation <!-- omit in toc -->
 
-Version    | Documentation
----------- | -------------
-unreleased | https://github.com/serradura/u-attributes/blob/main/README.md
-3.0.2      | https://github.com/serradura/u-attributes/blob/v3.x/README.md
-2.8.0      | https://github.com/serradura/u-attributes/blob/v2.x/README.md
+| Version    | Documentation                                                 |
+| ---------- | ------------------------------------------------------------- |
+| unreleased | https://github.com/serradura/u-attributes/blob/main/README.md |
+| 3.1.0      | https://github.com/serradura/u-attributes/blob/v3.x/README.md |
+| 2.8.0      | https://github.com/serradura/u-attributes/blob/v2.x/README.md |
 
 # Table of contents <!-- omit in toc -->
+
 - [Installation](#installation)
 - [Compatibility](#compatibility)
-- [Usage](#usage)
-  - [How to define attributes?](#how-to-define-attributes)
-    - [`Micro::Attributes#attributes=`](#microattributesattributes)
-      - [How to extract attributes from an object or hash?](#how-to-extract-attributes-from-an-object-or-hash)
-      - [Is it possible to define an attribute as required?](#is-it-possible-to-define-an-attribute-as-required)
-    - [`Micro::Attributes#attribute`](#microattributesattribute)
-    - [`Micro::Attributes#attribute!`](#microattributesattribute-1)
-    - [Attribute visibility (`private:`, `protected:`)](#attribute-visibility-private-protected)
-    - [Freezing attribute values (`freeze:`)](#freezing-attribute-values-freeze)
-  - [How to define multiple attributes?](#how-to-define-multiple-attributes)
-  - [`Micro::Attributes.with(:initialize)`](#microattributeswithinitialize)
-    - [`#with_attribute()`](#with_attribute)
-    - [`#with_attributes()`](#with_attributes)
-  - [Defining default values to the attributes](#defining-default-values-to-the-attributes)
-  - [The strict initializer](#the-strict-initializer)
-  - [Is it possible to inherit the attributes?](#is-it-possible-to-inherit-the-attributes)
-    - [`.attribute!()`](#attribute)
-  - [How to query the attributes?](#how-to-query-the-attributes)
-    - [`.attributes`](#attributes)
-    - [`.attribute?()`](#attribute-1)
-    - [`#attribute?()`](#attribute-2)
-    - [`#attributes()`](#attributes-1)
-      - [`#attributes(keys_as:)`](#attributeskeys_as)
-      - [`#attributes(*names)`](#attributesnames)
-      - [`#attributes([names])`](#attributesnames-1)
-      - [`#attributes(with:, without:)`](#attributeswith-without)
-    - [`#defined_attributes`](#defined_attributes)
-- [Built-in extensions](#built-in-extensions)
-  - [Picking specific features](#picking-specific-features)
-    - [`Micro::Attributes.with`](#microattributeswith)
-    - [`Micro::Attributes.without`](#microattributeswithout)
-  - [Picking all the features](#picking-all-the-features)
-  - [Extensions](#extensions)
-    - [Accept extension](#accept-extension)
-    - [`ActiveModel::Validation` extension](#activemodelvalidation-extension)
-      - [`.attribute()` options](#attribute-options)
-    - [Diff extension](#diff-extension)
-    - [Initialize extension](#initialize-extension)
-      - [Strict mode](#strict-mode)
-    - [Keys as symbol extension](#keys-as-symbol-extension)
+- [Feature overview](#feature-overview)
+  - [What you get by default](#what-you-get-by-default)
+  - [Opt-in extensions](#opt-in-extensions)
+  - [Picking a combination](#picking-a-combination)
+- [Defining attributes](#defining-attributes)
+  - [`attribute` and `attributes`](#attribute-and-attributes)
+  - [Defaults](#defaults)
+  - [Required attributes](#required-attributes)
+  - [Visibility (`private:`, `protected:`)](#visibility-private-protected)
+  - [Freezing values (`freeze:`)](#freezing-values-freeze)
+  - [Inheritance and `.attribute!`](#inheritance-and-attribute)
+- [The initialize extension](#the-initialize-extension)
+  - [Standard mode](#standard-mode)
+  - [Strict mode](#strict-mode)
+  - [`#with_attribute()`](#with_attribute)
+  - [`#with_attributes()`](#with_attributes)
+  - [Extracting attributes from another object or hash](#extracting-attributes-from-another-object-or-hash)
+  - [Writing your own constructor](#writing-your-own-constructor)
+- [Reading attributes](#reading-attributes)
+  - [Class-level: `.attributes`, `.attribute?`](#class-level-attributes-attribute)
+  - [Instance-level: `#attribute`, `#attribute!`, `#attribute?`](#instance-level-attribute-attribute-attribute)
+  - [The `#attributes` hash](#the-attributes-hash)
+    - [`keys_as:` — control key type](#keys_as--control-key-type)
+    - [Slicing with `*names` or `[names]`](#slicing-with-names-or-names)
+    - [`with:` and `without:`](#with-and-without)
+  - [`#defined_attributes`](#defined_attributes)
+- [Other extensions](#other-extensions)
+  - [Accept extension](#accept-extension)
+    - [What can `accept:` / `reject:` receive?](#what-can-accept--reject-receive)
+    - [`allow_nil:` option](#allow_nil-option)
+    - [`rejection_message:` option](#rejection_message-option)
+    - [Strict mode (`accept: :strict`)](#strict-mode-accept-strict)
+    - [Interaction with other features](#interaction-with-other-features)
+  - [ActiveModel validations extension](#activemodel-validations-extension)
+  - [Diff extension](#diff-extension)
+  - [Keys as Symbol extension](#keys-as-symbol-extension)
+- [Composition](#composition)
+  - [`Micro::Attributes.new`](#microattributesnew)
+    - [Enabling extensions](#enabling-extensions)
+  - [Nested attributes via `accept:`](#nested-attributes-via-accept)
+  - [Defining nested attributes inline (block form)](#defining-nested-attributes-inline-block-form)
+    - [Per-block extensions](#per-block-extensions)
+  - [Deep nesting \& validation bubbling](#deep-nesting--validation-bubbling)
+    - [Accept-error bubbling (no ActiveModel needed)](#accept-error-bubbling-no-activemodel-needed)
+    - [ActiveModel deep validation](#activemodel-deep-validation)
+- [Notes](#notes)
+  - [What "immutable" means here (and thread safety)](#what-immutable-means-here-and-thread-safety)
+  - [Unknown keys in `extract_attributes_from`](#unknown-keys-in-extract_attributes_from)
+  - [Migrating from 2.x](#migrating-from-2x)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -82,16 +149,16 @@ gem 'u-attributes', '~> 3.0'
 
 # Compatibility
 
-| u-attributes     | branch | ruby     | activemodel    |
-| ---------------- | ------ | -------- | -------------- |
-| unreleased       | main   | >= 2.7   | >= 6.0         |
-| 3.0.2            | v3.x   | >= 2.7   | >= 6.0         |
-| 2.8.0            | v2.x   | >= 2.2.0 | >= 3.2, <= 8.1 |
+| u-attributes | branch | ruby     | activemodel    |
+| ------------ | ------ | -------- | -------------- |
+| unreleased   | main   | >= 2.7   | >= 6.0         |
+| 3.1.0        | v3.x   | >= 2.7   | >= 6.0         |
+| 2.8.0        | v2.x   | >= 2.2.0 | >= 3.2, <= 8.1 |
 
 This library is tested (CI matrix) against:
 
 | Ruby / Rails | 6.0 | 6.1 | 7.0 | 7.1 | 7.2 | 8.0 | 8.1 | Edge |
-|--------------|-----|-----|-----|-----|-----|-----|-----|------|
+| ------------ | --- | --- | --- | --- | --- | --- | --- | ---- |
 | 2.7          | ✅  | ✅  | ✅  | ✅  |     |     |     |      |
 | 3.0          | ✅  | ✅  | ✅  | ✅  |     |     |     |      |
 | 3.1          |     |     | ✅  | ✅  | ✅  |     |     |      |
@@ -101,172 +168,150 @@ This library is tested (CI matrix) against:
 | 4.x          |     |     |     |     |     |     | ✅  | ✅   |
 | Head         |     |     |     |     |     |     | ✅  | ✅   |
 
-> **Note**: The activemodel is an optional dependency, this module [can be enabled](#activemodelvalidation-extension) to validate the attributes.
-
-[⬆️ Back to Top](#table-of-contents-)
-
-# Usage
+> **Note:** `activemodel` is an optional dependency; the [ActiveModel validations extension](#activemodel-validations-extension) needs it.
 
-## How to define attributes?
+# Feature overview
 
-By default, you must define the class constructor.
-
-```ruby
-class Person
-  include Micro::Attributes
+`u-attributes` is a small core (`include Micro::Attributes`) plus opt-in extensions. The two tables below map every feature in the gem so you can scan what's possible before diving into details.
 
-  attribute :age
-  attribute :name
+## What you get by default
 
-  def initialize(name: 'John Doe', age:)
-    @name, @age = name, age
-  end
-end
+Everything in this table is available the moment you `include Micro::Attributes` — no `.with(...)` required.
 
-person = Person.new(age: 21)
+| Capability                | Example                                            | Notes                                                                                                     |
+| ------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Define an attribute       | `attribute :name`                                  | Public reader; no setter                                                                                  |
+| Define many at once       | `attributes :a, :b, default: 0`                    | Trailing options apply to every name                                                                      |
+| Override in a subclass    | `attribute! :name, default: 'X'`                   | Subclass-only                                                                                             |
+| Default value             | `attribute :name, default: 'X'`                    | Static value or `proc { ... }` / `->(v) { ... }`                                                          |
+| Required (without strict) | `attribute :name, required: true`                  | Raises on missing key if `attributes=` is invoked with one                                                |
+| Freeze the value          | `attribute :name, freeze: true`                    | Also `:after_dup`, `:after_clone`                                                                         |
+| Visibility                | `attribute :secret, private: true`                 | Or `protected: true`; hidden from `#attributes` hash                                                      |
+| Layer extensions inline   | `with :keys_as_symbol`                             | Class macro — see [Opt-in extensions](#opt-in-extensions)                                                 |
+| Block-form nested         | `attribute :foo do ... end`                        | Anonymous inline class; inherits the host's feature mix                                                   |
+| Hash → child coercion     | `attribute :child, accept: Other`                  | When `Other` includes `Micro::Attributes`, a hash auto-builds an instance                                 |
+| Deep-error bubble marker  | `parent.attributes_errors['child']`                | Descendant errors mirror up as `'is invalid'` (requires `:accept` on the parent so the error hash exists) |
+| Struct-style factory      | `User = Micro::Attributes.new { attribute :name }` | Returns a class; preset is `initialize: true, accept: true`                                               |
 
-person.age  # 21
-person.name # John Doe
+## Opt-in extensions
 
-# By design the attributes are always exposed as reader methods (getters).
-# If you try to call a setter you will see a NoMethodError.
-#
-# person.name = 'Rodrigo'
-# NoMethodError (undefined method `name=' for #<Person:0x0000... @name='John Doe', @age=21>)
-```
+Mix any combination via `Micro::Attributes.with(...)` — hash-style and positional-symbol APIs both work and can be combined.
 
-[⬆️ Back to Top](#table-of-contents-)
+| Extension                   | Hash API                     | Positional API             | What it adds                                                                                                                                                                                                                                   |
+| --------------------------- | ---------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Initialize**              | `initialize: true`           | `:initialize`              | Auto-generated `new(hash)` constructor + immutable `#with_attribute(s)`                                                                                                                                                                        |
+| **Initialize (strict)**     | `initialize: :strict`        | (hash only)                | All attributes without a default become **required**; missing keys raise `ArgumentError`. Implies `Initialize`.                                                                                                                                |
+| **Accept**                  | `accept: true`               | `:accept`                  | `accept:` / `reject:` / `allow_nil:` / `rejection_message:` validation; `#attributes_errors`, `#attributes_errors?`, `#accepted_attributes`, `#rejected_attributes`                                                                            |
+| **Accept (strict)**         | `accept: :strict`            | (hash only)                | Any rejection raises `ArgumentError` immediately. Implies `Accept`.                                                                                                                                                                            |
+| **Diff**                    | `diff: true`                 | `:diff`                    | `#diff_attributes(other)` returns a `Diff::Changes` (`#changed?`, `#differences`, etc.)                                                                                                                                                        |
+| **Keys as Symbol**          | `keys_as: :symbol`           | `:keys_as_symbol`          | Symbol-keyed storage; disables indifferent access for performance/strictness                                                                                                                                                                   |
+| **ActiveModel Validations** | `active_model: :validations` | `:activemodel_validations` | Mixes `ActiveModel::Validations` (`valid?`, `errors`, `validates :x, presence: true`, the `validates:` / `validate:` attribute options); `parent.valid?` bubbles **deep** descendant invalidity into `errors`. Requires the `activemodel` gem. |
 
-### `Micro::Attributes#attributes=`
+## Picking a combination
 
-This is a protected method to make easier the assignment in a constructor. e.g.
+Two equivalent ways to enable features:
 
 ```ruby
-class Person
-  include Micro::Attributes
-
-  attribute :age
-  attribute :name, default: 'John Doe'
-
-  def initialize(options)
-    self.attributes = options
-  end
-end
-
-person = Person.new(age: 20)
+# Hash style — self-documenting; great when you're enabling several
+Micro::Attributes.with(
+  diff:         true,
+  accept:       true,    # :strict,
+  keys_as:      :symbol, # :string | :indifferent (default),
+  initialize:   true,    # :strict,
+  active_model: :validations
+)
 
-person.age  # 20
-person.name # John Doe
+# Positional style — terser when you're just turning things on
+include Micro::Attributes.with(:initialize, :accept, :diff, :keys_as_symbol)
 ```
 
-#### How to extract attributes from an object or hash?
-
-You can extract attributes using the `extract_attributes_from` method. For each attribute name it
-will first call the reader method (`object.attribute_key`) when available, and fall back to the
-hash accessor (`object[attribute_key]`) otherwise. The reader method has priority because it lets
-the source object encapsulate any computed/derived value.
-
-```ruby
-class Person
-  include Micro::Attributes
-
-  attribute :age
-  attribute :name, default: 'John Doe'
+Rules:
 
-  def initialize(user:)
-    self.attributes = extract_attributes_from(user)
-  end
-end
+- Omit a key (or pass `false` / `nil`) to disable a feature.
+- `keys_as: :string` and `keys_as: :indifferent` are no-ops (the default); only `:symbol` activates `KeysAsSymbol`.
+- The two forms can be mixed in a single call: `Micro::Attributes.with(:initialize, accept: :strict)`.
+- Strict variants are hash-only: `Micro::Attributes.with(initialize: :strict, accept: :strict)`.
 
-# extracting from an object
+Calling `with` with no arguments raises:
 
-class User
-  attr_accessor :age, :name
+```ruby
+class Job
+  include Micro::Attributes.with() # ArgumentError (Invalid feature name! Available options: :accept, :activemodel_validations, :diff, :initialize, :keys_as_symbol)
 end
+```
 
-user = User.new
-user.age = 20
+To enable every feature at once, use `Micro::Attributes.with_all_features` — equivalent to the full strict mix:
 
-person = Person.new(user: user)
+```ruby
+Micro::Attributes.with_all_features
 
-person.age  # 20
-person.name # John Doe
+# Same as:
+Micro::Attributes.with(:accept, :activemodel_validations, :diff, :keys_as_symbol, initialize: :strict)
+```
 
-# extracting from a hash
+Use `Micro::Attributes.without(:feature, ...)` to exclude features from the full set (e.g. `Micro::Attributes.without(:diff)` loads everything except Diff).
 
-another_person = Person.new(user: { age: 55, name: 'Julia Not Roberts' })
+The same `with(...)` is also a class macro — `class X; include Micro::Attributes.with(:initialize); with diff: true; end` layers more features on top of an existing include. It's also callable inside an `attribute :foo do ... end` block to layer features onto just that inline child; see [Per-block extensions](#per-block-extensions).
 
-another_person.age  # 55
-another_person.name # Julia Not Roberts
-```
+[⬆️ Back to top](#-attributes)
 
-#### Is it possible to define an attribute as required?
+# Defining attributes
 
-You only need to use the `required: true` option.
+## `attribute` and `attributes`
 
-But to this work, you need to assign the attributes using the [`#attributes=`](#microattributesattributes) method or the extensions: [initialize](#initialize-extension), [activemodel_validations](#activemodelvalidation-extension).
+Use `.attribute` for a single name, and `.attributes` (plural) for several names that share the same options.
 
 ```ruby
 class Person
-  include Micro::Attributes
-
-  attribute :age
-  attribute :name, required: true
+  include Micro::Attributes.with(:initialize)
 
-  def initialize(attributes)
-    self.attributes = attributes
-  end
+  attribute  :name
+  attributes :age, :score, default: 0
 end
 
-Person.new(age: 32) # ArgumentError (missing keyword: :name)
+Person.new(name: 'Ada').name # "Ada"
+Person.new(name: 'Ada').age  # 0
 ```
 
-[⬆️ Back to Top](#table-of-contents-)
+> `.attributes` accepts a single trailing options hash and applies it to every name in the list. If you need different options per attribute, call `.attribute` once per attribute.
 
-### `Micro::Attributes#attribute`
+## Defaults
 
-Use this method with a valid attribute name to get its value.
+Pass `default:` with either a static value or a callable.
 
 ```ruby
-person = Person.new(age: 20)
-
-person.attribute('age') # 20
-person.attribute(:name) # John Doe
-person.attribute('foo') # nil
-```
-
-If you pass a block, it will be executed only if the attribute was valid.
+class Person
+  include Micro::Attributes.with(:initialize)
 
-```ruby
-person.attribute(:name) { |value| puts value } # John Doe
-person.attribute('age') { |value| puts value } # 20
-person.attribute('foo') { |value| puts value } # !! Nothing happened, because of the attribute doesn't exist.
+  attribute :age,  default: -> v { v&.to_i }
+  attribute :name, default: ->(name) { String(name || 'John Doe').strip }
+end
 ```
 
-[⬆️ Back to Top](#table-of-contents-)
+If the callable takes an argument, it receives the incoming value and can transform it before assignment.
 
-### `Micro::Attributes#attribute!`
+## Required attributes
 
-Works like the `#attribute` method, but it will raise an exception when the attribute doesn't exist.
+`required: true` raises when the key is missing from the constructor:
 
 ```ruby
-person.attribute!('foo')                   # NameError (undefined attribute `foo)
+class Person
+  include Micro::Attributes.with(:initialize)
+
+  attribute :age
+  attribute :name, required: true
+end
 
-person.attribute!('foo') { |value| value } # NameError (undefined attribute `foo)
+Person.new(age: 32) # ArgumentError (missing keyword: :name)
 ```
 
-[⬆️ Back to Top](#table-of-contents-)
+For a class-wide version, see [Strict mode](#strict-mode) on the initialize extension — it makes every attribute without a default required.
 
-### Attribute visibility (`private:`, `protected:`)
+## Visibility (`private:`, `protected:`)
 
-By default every attribute reader is `public`. Use the `private: true` or `protected: true`
-options to restrict the reader's visibility — useful for things like passwords, tokens, and any
-internal value you don't want to expose on the public API.
+By default every attribute reader is `public`. Use `private: true` or `protected: true` to restrict it — useful for things like passwords, tokens, and any internal value you don't want to expose on the public API.
 
-Private/protected attributes are also excluded from the public attribute set (`#attributes`,
-`.attributes`, `#attribute?`), so they don't leak through serialization or enumeration. To check
-or fetch them explicitly, pass `true` as the second argument to `#attribute?` (or use
-`#attribute!`).
+Private/protected attributes are also excluded from the public attribute set (`#attributes`, `.attributes`, `#attribute?`), so they don't leak through serialization or enumeration. To check or fetch them explicitly, pass `true` as the second argument to `#attribute?` (or use `#attribute!`).
 
 ```ruby
 require 'digest'
@@ -276,7 +321,8 @@ class User::SignUpParams
 
   TrimString = ->(value) { String(value).strip }
 
-  attribute  :email,                                              default: TrimString
+  attribute :email, default: TrimString
+
   attributes :password, :password_confirmation, default: TrimString, private: true
 
   def password_digest
@@ -295,37 +341,32 @@ user = User::SignUpParams.new(
   password_confirmation: 'secret'
 )
 
-user.attributes                  # { "email" => "email@example.com" }
+user.attributes                   # { "email" => "email@example.com" }
 
-user.attribute?('email')         # true
-user.attribute?('password')      # false  (not in the public set)
+user.attribute?('email')          # true
+user.attribute?('password')       # false  (not in the public set)
 user.attribute?('password', true) # true   (use the second arg to look at all attributes)
 
-user.attribute('password')       # nil     (returns nil instead of leaking the value)
-user.attribute!('password')      # NameError ("tried to access a private attribute `password")
+user.attribute('password')        # nil     (returns nil instead of leaking the value)
+user.attribute!('password')       # NameError ("tried to access a private attribute `password")
 
-user.password                    # NoMethodError (private method `password' called for ...)
+user.password                     # NoMethodError (private method `password' called for ...)
 ```
 
 - `private:` and `protected:` map directly to Ruby's method-visibility semantics on the reader.
 - The visibility configuration is preserved on inheritance.
-- Works with the `:keys_as_symbol` extension (`attributes_by_visibility` will return the keys in
-  the configured type).
-
-The class-level `attributes_by_visibility` method returns a hash with `:public`, `:private`, and
-`:protected` keys so you can introspect how each attribute was declared.
+- Works with the `:keys_as_symbol` extension (`attributes_by_visibility` will return the keys in the configured type).
 
-[⬆️ Back to Top](#table-of-contents-)
+The class-level `attributes_by_visibility` method returns a hash with `:public`, `:private`, and `:protected` keys so you can introspect how each attribute was declared.
 
-### Freezing attribute values (`freeze:`)
+## Freezing values (`freeze:`)
 
-Use the `freeze:` option to make sure the value stored in the attribute can't be mutated after
-the object is built. Three modes are supported:
+Use `freeze:` to make sure the value stored in the attribute can't be mutated after the object is built. Three modes are supported:
 
-| Value          | Behavior                                                              |
-| -------------- | --------------------------------------------------------------------- |
-| `true`         | Calls `value.freeze` on the incoming value. The original is frozen.   |
-| `:after_dup`   | `value.dup.freeze` — freezes a shallow copy; the original stays free. |
+| Value          | Behavior                                                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `true`         | Calls `value.freeze` on the incoming value. The original is frozen.                                                      |
+| `:after_dup`   | `value.dup.freeze` — freezes a shallow copy; the original stays free.                                                    |
 | `:after_clone` | `value.clone.freeze` — same as above but uses `#clone` (preserves singleton methods, frozen state, tainted state, etc.). |
 
 ```ruby
@@ -337,121 +378,140 @@ class Person
   attribute :payload, freeze: :after_clone
 end
 
-raw_name = +"Rodrigo"
+raw_name    = +"Rodrigo"
+raw_address = +"Av. Paulista"
 
 person = Person.new(
   name:    raw_name,
-  address: 'Av. Paulista',
+  address: raw_address,
   payload: { id: 1 }
 )
 
-person.name.frozen?    # true
-raw_name.frozen?       # true  -> freeze: true mutates the original
+person.name.frozen?     # true
+raw_name.frozen?        # true   ← freeze: true mutates the original
 
-person.address.frozen? # true
-'Av. Paulista'.frozen? # depends on the source string; the duplicate is what's frozen
+person.address.frozen?  # true
+raw_address.frozen?     # false  ← :after_dup freezes only the copy
 ```
 
-`freeze:` is applied after the default value resolution, so the frozen value reflects whatever
-the attribute ends up holding (raw value, default, or callable-default result).
+`freeze:` is applied **after** the default value resolution, so the frozen value reflects whatever the attribute ends up holding (raw value, default, or callable-default result).
 
-[⬆️ Back to Top](#table-of-contents-)
+## Inheritance and `.attribute!`
 
-## How to define multiple attributes?
-
-Use `.attributes` with a list of attribute names.
+Attribute definitions are preserved through inheritance:
 
 ```ruby
 class Person
-  include Micro::Attributes
+  include Micro::Attributes.with(:initialize)
 
-  attributes :age, :name
+  attribute :age
+  attribute :name, default: 'John Doe'
+end
 
-  def initialize(options)
-    self.attributes = options
-  end
+class Subclass < Person
+  attribute :foo
 end
 
-person = Person.new(age: 32)
+instance = Subclass.new({})
 
-person.name # nil
-person.age  # 32
+instance.name              # "John Doe"
+instance.respond_to?(:age) # true
+instance.respond_to?(:foo) # true
 ```
 
-You can also pass a trailing options hash and every attribute in the list will be declared with
-those options. This is the canonical way to declare several attributes that share the same
-configuration (default value, visibility, freezing, validations, etc.).
+Use `.attribute!` to override an inherited attribute's options (e.g. its default):
 
 ```ruby
-class User::SignUpParams
-  include Micro::Attributes.with(:initialize, :accept)
+class AnotherSubclass < Person
+  attribute! :name, default: 'Alfa'
+end
 
-  TrimString = ->(value) { String(value).strip }
+AnotherSubclass.new({}).name # "Alfa"
 
-  attribute  :email,                                              default: TrimString
-  attributes :password, :password_confirmation, reject: :empty?,  default: TrimString, private: true
+class SubSubclass < Subclass
+  attribute! :age,  default: 0
+  attribute! :name, default: 'Beta'
 end
+
+SubSubclass.new({}).name # "Beta"
+SubSubclass.new({}).age  # 0
 ```
 
-> **Note:** Unlike `.attribute`, this method accepts a shared options hash but defines all listed
-> attributes with the same configuration. If you need different defaults/options per attribute,
-> use `#attribute()` once per attribute.
+[⬆️ Back to top](#-attributes)
 
-[⬆️ Back to Top](#table-of-contents-)
+# The initialize extension
 
-## `Micro::Attributes.with(:initialize)`
+`Micro::Attributes.with(:initialize)` generates a hash-keyword constructor plus the immutable update methods `#with_attribute` / `#with_attributes`. It's the path most projects want.
 
-Use `Micro::Attributes.with(:initialize)` to define a constructor to assign the attributes. e.g.
+## Standard mode
 
 ```ruby
 class Person
   include Micro::Attributes.with(:initialize)
 
-  attribute :age, required: true
+  attribute :age,  required: true
   attribute :name, default: 'John Doe'
 end
 
 person = Person.new(age: 18)
-
 person.age  # 18
-person.name # John Doe
+person.name # "John Doe"
+```
+
+## Strict mode
+
+`Micro::Attributes.with(initialize: :strict)` forbids instantiation without every attribute keyword — equivalent to declaring every attribute without a default as `required: true`.
+
+```ruby
+class StrictPerson
+  include Micro::Attributes.with(initialize: :strict)
+
+  attribute :age
+  attribute :name, default: 'John Doe'
+end
+
+StrictPerson.new({}) # ArgumentError (missing keyword: :age)
+
+# Attributes with a default may still be omitted:
+StrictPerson.new(age: nil).age  # nil
+StrictPerson.new(age: nil).name # "John Doe"
 ```
 
-This extension enables two methods for your objects.
-The `#with_attribute()` and `#with_attributes()`.
+Aside from that validation, strict mode behaves identically to the standard mode.
+
+## `#with_attribute()`
 
-### `#with_attribute()`
+Returns a new instance with one attribute updated. The original is untouched.
 
 ```ruby
 another_person = person.with_attribute(:age, 21)
 
 another_person.age            # 21
-another_person.name           # John Doe
+another_person.name           # "John Doe"
 another_person.equal?(person) # false
 ```
 
-### `#with_attributes()`
+## `#with_attributes()`
+
+Returns a new instance with multiple attributes updated.
 
-Use it to assign multiple attributes
 ```ruby
 other_person = person.with_attributes(name: 'Serradura', age: 32)
 
 other_person.age            # 32
-other_person.name           # Serradura
+other_person.name           # "Serradura"
 other_person.equal?(person) # false
 ```
 
-If you pass a value different of a Hash, a Kind::Error will be raised.
+Passing a non-Hash raises:
 
 ```ruby
-Person.new(1) # Kind::Error (1 expected to be a kind of Hash)
+person.with_attributes(1) # Kind::Error (1 expected to be a kind of Hash)
 ```
 
-[⬆️ Back to Top](#table-of-contents-)
+## Extracting attributes from another object or hash
 
-## Defining default values to the attributes
-
-To do this, you only need make use of the `default:` keyword. e.g.
+`extract_attributes_from` reads only the declared attribute names from any source — object or hash. For each name it first calls the reader method (`source.attribute_key`) when available and falls back to hash access (`source[attribute_key]`) otherwise. The reader has priority so the source object can expose a computed or derived value.
 
 ```ruby
 class Person
@@ -459,343 +519,166 @@ class Person
 
   attribute :age
   attribute :name, default: 'John Doe'
-end
-```
 
-There are two different strategies to define default values.
-1. Pass a regular object, like in the previous example.
-2. Pass a `proc`/`lambda`, and if it has an argument you will receive the attribute value to do something before assign it.
-
-```ruby
-class Person
-  include Micro::Attributes.with(:initialize)
-
-  attribute :age, default: -> age { age&.to_i }
-  attribute :name, default: -> name { String(name || 'John Doe').strip }
+  def self.from(source)
+    new(extract_attributes_from(source))
+  end
 end
-```
-
-[⬆️ Back to Top](#table-of-contents-)
-
-## The strict initializer
-
-Use `.with(initialize: :strict)` to forbids an instantiation without all the attribute keywords.
-
-In other words, it is equivalent to you define all the attributes using the [`required: true` option](#is-it-possible-to-define-an-attribute-as-required).
-
-```ruby
-class StrictPerson
-  include Micro::Attributes.with(initialize: :strict)
 
-  attribute :age
-  attribute :name, default: 'John Doe'
+# From an object:
+class User
+  attr_accessor :age, :name
 end
+user      = User.new
+user.age  = 20
+user.name = 'Alice'
 
-StrictPerson.new({}) # ArgumentError (missing keyword: :age)
-```
-
-An attribute with a default value can be omitted.
-
-``` ruby
-person_without_age = StrictPerson.new(age: nil)
+Person.from(user).age  # 20
+Person.from(user).name # "Alice"
 
-person_without_age.age  # nil
-person_without_age.name # 'John Doe'
+# From a hash:
+Person.from(age: 55, name: 'Julia Not Roberts').age  # 55
+Person.from(age: 55, name: 'Julia Not Roberts').name # "Julia Not Roberts"
 ```
 
-> **Note:** Except for this validation the `.with(initialize: :strict)` method will works in the same ways of `.with(:initialize)`.
-
-[⬆️ Back to Top](#table-of-contents-)
+Unknown keys on the source are silently ignored — only declared attributes are read.
 
-## Is it possible to inherit the attributes?
+## Writing your own constructor
 
-Yes. e.g.
+If you need a custom constructor instead of `.with(:initialize)`, include the bare module and assign attributes through the protected `attributes=` setter:
 
 ```ruby
 class Person
-  include Micro::Attributes.with(:initialize)
+  include Micro::Attributes
 
   attribute :age
   attribute :name, default: 'John Doe'
-end
-
-class Subclass < Person # Will preserve the parent class attributes
-  attribute :foo
-end
-
-instance = Subclass.new({})
-
-instance.name              # John Doe
-instance.respond_to?(:age) # true
-instance.respond_to?(:foo) # true
-```
 
-[⬆️ Back to Top](#table-of-contents-)
-
-### `.attribute!()`
-
-This method allows us to redefine the attributes default data that was defined in the parent class. e.g.
-
-```ruby
-class AnotherSubclass < Person
-  attribute! :name, default: 'Alfa'
-end
-
-alfa_person = AnotherSubclass.new({})
-
-alfa_person.name # 'Alfa'
-alfa_person.age  # nil
-
-class SubSubclass < Subclass
-  attribute! :age, default: 0
-  attribute! :name, default: 'Beta'
+  def initialize(options)
+    self.attributes = options
+  end
 end
 
-beta_person = SubSubclass.new({})
-
-beta_person.name # 'Beta'
-beta_person.age  # 0
+Person.new(age: 20).age  # 20
+Person.new(age: 20).name # "John Doe"
 ```
 
-[⬆️ Back to Top](#table-of-contents-)
+`extract_attributes_from` works here too. Note that `#with_attribute` / `#with_attributes` and the strict-mode constructor validation are only available when the `:initialize` extension is loaded.
 
-## How to query the attributes?
+[⬆️ Back to top](#-attributes)
 
-All of the methods that will be explained can be used with any of the built-in extensions.
+# Reading attributes
 
-**PS:** We will use the class below for all of the next examples.
+All of the methods below work with any feature mix. The examples use:
 
 ```ruby
 class Person
-  include Micro::Attributes
+  include Micro::Attributes.with(:initialize)
 
   attribute :age
   attribute :first_name, default: 'John'
-  attribute :last_name, default: 'Doe'
-
-  def initialize(options)
-    self.attributes = options
-  end
+  attribute :last_name,  default: 'Doe'
 
   def name
     "#{first_name} #{last_name}"
   end
 end
-```
 
-### `.attributes`
+person = Person.new(age: 20)
+```
 
-Listing all the class attributes.
+## Class-level: `.attributes`, `.attribute?`
 
 ```ruby
 Person.attributes # ["age", "first_name", "last_name"]
-```
 
-### `.attribute?()`
-
-Checking the existence of some attribute.
-
-```ruby
 Person.attribute?(:first_name)  # true
 Person.attribute?('first_name') # true
-
-Person.attribute?('foo') # false
-Person.attribute?(:foo)  # false
+Person.attribute?('foo')        # false
 ```
 
-### `#attribute?()`
+## Instance-level: `#attribute`, `#attribute!`, `#attribute?`
 
-Checking the existence of some attribute in an instance.
+`#attribute(name)` returns the attribute's value (or `nil` if the name isn't declared). It accepts a block that fires only when the name is valid:
 
 ```ruby
-person = Person.new(age: 20)
-
-person.attribute?(:name)  # true
-person.attribute?('name') # true
+person.attribute('age')        # 20
+person.attribute(:first_name)  # "John"
+person.attribute('foo')        # nil
 
-person.attribute?('foo') # false
-person.attribute?(:foo)  # false
+person.attribute('age') { |value| puts value } # prints 20
+person.attribute('foo') { |value| puts value } # nothing — name doesn't exist
 ```
 
-### `#attributes()`
-
-Fetching all the attributes with their values.
+`#attribute!(name)` does the same but raises on an unknown name:
 
 ```ruby
-person1 = Person.new(age: 20)
-person1.attributes # {"age"=>20, "first_name"=>"John", "last_name"=>"Doe"}
-
-person2 = Person.new(first_name: 'Rodrigo', last_name: 'Rodrigues')
-person2.attributes # {"age"=>nil, "first_name"=>"Rodrigo", "last_name"=>"Rodrigues"}
+person.attribute!('foo') # NameError (undefined attribute `foo)
 ```
 
-#### `#attributes(keys_as:)`
-
-Use the `keys_as:` option with `Symbol`/`:symbol` or `String`/`:string` to transform the attributes hash keys.
+`#attribute?(name)` reports whether the name is a declared, publicly visible attribute:
 
 ```ruby
-person1 = Person.new(age: 20)
-person2 = Person.new(first_name: 'Rodrigo', last_name: 'Rodrigues')
-
-person1.attributes(keys_as: Symbol) # {:age=>20, :first_name=>"John", :last_name=>"Doe"}
-person2.attributes(keys_as: String) # {"age"=>nil, "first_name"=>"Rodrigo", "last_name"=>"Rodrigues"}
-
-person1.attributes(keys_as: :symbol) # {:age=>20, :first_name=>"John", :last_name=>"Doe"}
-person2.attributes(keys_as: :string) # {"age"=>nil, "first_name"=>"Rodrigo", "last_name"=>"Rodrigues"}
+person.attribute?(:first_name) # true
+person.attribute?('foo')       # false
 ```
 
-#### `#attributes(*names)`
-
-Slices the attributes to include only the given keys (in their types).
-
-```ruby
-person = Person.new(age: 20)
-
-person.attributes(:age)               # {:age => 20}
-person.attributes(:age, :first_name)  # {:age => 20, :first_name => "John"}
-person.attributes('age', 'last_name') # {"age" => 20, "last_name" => "Doe"}
-
-person.attributes(:age, 'last_name') # {:age => 20, "last_name" => "Doe"}
-
-# You could also use the keys_as: option to ensure the same type for all of the hash keys.
-
-person.attributes(:age, 'last_name', keys_as: Symbol) # {:age=>20, :last_name=>"Doe"}
-```
+Pass `true` as the second argument to include private/protected attributes — see [Visibility](#visibility-private-protected).
 
-#### `#attributes([names])`
+## The `#attributes` hash
 
-As the previous example, this methods accepts a list of keys to slice the attributes.
+The bare call returns every public attribute with its current value:
 
 ```ruby
-person = Person.new(age: 20)
-
-person.attributes([:age])               # {:age => 20}
-person.attributes([:age, :first_name])  # {:age => 20, :first_name => "John"}
-person.attributes(['age', 'last_name']) # {"age" => 20, "last_name" => "Doe"}
-
-person.attributes([:age, 'last_name']) # {:age => 20, "last_name" => "Doe"}
-
-# You could also use the keys_as: option to ensure the same type for all of the hash keys.
-
-person.attributes([:age, 'last_name'], keys_as: Symbol) # {:age=>20, :last_name=>"Doe"}
+person.attributes # {"age"=>20, "first_name"=>"John", "last_name"=>"Doe"}
 ```
 
-#### `#attributes(with:, without:)`
+### `keys_as:` — control key type
 
-Use the `with:` option to include any method value of the instance inside of the hash, and,
-you can use the `without:` option to exclude one or more attribute keys from the final hash.
+Pass `keys_as: Symbol`/`:symbol` or `String`/`:string` to coerce hash keys:
 
 ```ruby
-person = Person.new(age: 20)
-
-person.attributes(without: :age)               # {"first_name"=>"John", "last_name"=>"Doe"}
-person.attributes(without: [:age, :last_name]) # {"first_name"=>"John"}
-
-person.attributes(with: [:name], without: [:first_name, :last_name]) # {"age"=>20, "name"=>"John Doe"}
-
-# To achieves the same output of the previous example, use the attribute names to slice only them.
-
-person.attributes(:age, with: [:name]) # {:age=>20, "name"=>"John Doe"}
-
-# You could also use the keys_as: option to ensure the same type for all of the hash keys.
-
-person.attributes(:age, with: [:name], keys_as: Symbol) # {:age=>20, :name=>"John Doe"}
-```
-
-### `#defined_attributes`
-
-Listing all the available attributes.
-
-```ruby
-person = Person.new(age: 20)
-
-person.defined_attributes # ["age", "first_name", "last_name"]
+person.attributes(keys_as: Symbol)  # {:age=>20, :first_name=>"John", :last_name=>"Doe"}
+person.attributes(keys_as: :string) # {"age"=>20, "first_name"=>"John", "last_name"=>"Doe"}
 ```
 
-[⬆️ Back to Top](#table-of-contents-)
-
-# Built-in extensions
-
-You can use the method `Micro::Attributes.with()` to combine and require only the features that better fit your needs.
-
-But, if you desire except one or more features, use the `Micro::Attributes.without()` method.
+### Slicing with `*names` or `[names]`
 
-## Picking specific features
-
-### `Micro::Attributes.with`
+Both shapes accept a list of attribute names and slice the hash. Key type is preserved per argument unless `keys_as:` is also supplied:
 
 ```ruby
-Micro::Attributes.with(:initialize)
-
-Micro::Attributes.with(:initialize, :keys_as_symbol)
-
-Micro::Attributes.with(:keys_as_symbol, initialize: :strict)
-
-Micro::Attributes.with(:diff, :initialize)
-
-Micro::Attributes.with(:diff, initialize: :strict)
-
-Micro::Attributes.with(:diff, :keys_as_symbol, initialize: :strict)
-
-Micro::Attributes.with(:activemodel_validations)
-
-Micro::Attributes.with(:activemodel_validations, :diff)
-
-Micro::Attributes.with(:activemodel_validations, :diff, initialize: :strict)
-
-Micro::Attributes.with(:activemodel_validations, :diff, :keys_as_symbol, initialize: :strict)
-```
-
-The method `Micro::Attributes.with()` will raise an exception if no arguments/features were declared.
-
-```ruby
-class Job
-  include Micro::Attributes.with() # ArgumentError (Invalid feature name! Available options: :accept, :activemodel_validations, :diff, :initialize, :keys_as_symbol)
-end
+person.attributes(:age, :first_name)                  # {:age=>20, :first_name=>"John"}
+person.attributes(['age', 'last_name'])               # {"age"=>20, "last_name"=>"Doe"}
+person.attributes(:age, 'last_name')                  # {:age=>20, "last_name"=>"Doe"}
+person.attributes(:age, 'last_name', keys_as: Symbol) # {:age=>20, :last_name=>"Doe"}
 ```
 
-### `Micro::Attributes.without`
+### `with:` and `without:`
 
-Picking *except* one or more features
+`with:` includes the value of additional instance methods; `without:` excludes attribute keys:
 
 ```ruby
-Micro::Attributes.without(:diff) # will load :activemodel_validations, :keys_as_symbol and initialize: :strict
-
-Micro::Attributes.without(initialize: :strict) # will load :activemodel_validations, :diff and :keys_as_symbol
+person.attributes(without: :age)                                     # {"first_name"=>"John", "last_name"=>"Doe"}
+person.attributes(with: [:name], without: [:first_name, :last_name]) # {"age"=>20, "name"=>"John Doe"}
+person.attributes(:age, with: [:name])                               # {:age=>20, "name"=>"John Doe"}
+person.attributes(:age, with: [:name], keys_as: Symbol)              # {:age=>20, :name=>"John Doe"}
 ```
 
-You can also pair `:accept` with any other feature, and switch into strict mode by passing the
-hash form `accept: :strict`:
-
-```ruby
-Micro::Attributes.with(:accept)
-
-Micro::Attributes.with(:accept, :diff, :initialize)
+## `#defined_attributes`
 
-Micro::Attributes.with(:accept, :activemodel_validations, :diff, :keys_as_symbol)
-
-Micro::Attributes.with(:diff, :keys_as_symbol, initialize: :strict, accept: :strict)
-```
-
-## Picking all the features
+Returns the list of attribute names declared on the instance's class. Unlike `Person.attributes` (which requires the class on hand) or `#attributes` (which returns values), `#defined_attributes` gives you just the names from any instance — handy in serializers, decorators, or generic code that traverses arbitrary objects.
 
 ```ruby
-Micro::Attributes.with_all_features
-
-# This method returns the same of:
-
-Micro::Attributes.with(:accept, :activemodel_validations, :diff, :keys_as_symbol, initialize: :strict)
+person.defined_attributes # ["age", "first_name", "last_name"]
 ```
 
-[⬆️ Back to Top](#table-of-contents-)
+[⬆️ Back to top](#-attributes)
 
-## Extensions
+# Other extensions
 
-### Accept extension
+## Accept extension
 
-The `:accept` extension adds a lightweight, dependency-free validation mechanism. Use the
-`accept:` / `reject:` options on an attribute to validate the assigned value, and inspect the
-result through `#attributes_errors`, `#accepted_attributes`, and `#rejected_attributes`.
+The `:accept` extension adds lightweight, dependency-free value validation. Use the `accept:` / `reject:` options on an attribute to validate the assigned value, then inspect the result through `#attributes_errors`, `#accepted_attributes`, and `#rejected_attributes`.
 
 ```ruby
 class User
@@ -807,7 +690,6 @@ class User
 end
 
 user = User.new({})
-
 user.attributes_errors?   # false
 user.accepted_attributes? # true
 user.rejected_attributes? # false
@@ -820,26 +702,25 @@ User.new(age: 'twenty', email: nil).tap do |bad|
 end
 ```
 
-#### What can `accept:` / `reject:` receive?
+### What can `accept:` / `reject:` receive?
 
-| Type            | `accept:` means                              | `reject:` means                                  |
-| --------------- | -------------------------------------------- | ------------------------------------------------ |
-| `Class`/`Module`| `value.kind_of?(expected)` must be true      | `value.kind_of?(expected)` must be false         |
-| Predicate `:sym?` (ends with `?`) | `value.public_send(:sym?)` must be true | `value.public_send(:sym?)` must be false |
+| Type                                                           | `accept:` means                                 | `reject:` means                                |
+| -------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------- |
+| `Class`/`Module`                                               | `value.kind_of?(expected)` must be true         | `value.kind_of?(expected)` must be false       |
+| Predicate `:sym?` (ends with `?`)                              | `value.public_send(:sym?)` must be true         | `value.public_send(:sym?)` must be false       |
 | Anything callable (proc, lambda, object responding to `#call`) | result of `expected.call(value)` must be truthy | result of `expected.call(value)` must be falsy |
 
-Default rejection messages follow the pattern below; you can override them with
-`rejection_message:` (see further down).
+Default rejection messages follow the pattern below; override them with `rejection_message:` (next subsection).
 
 ```ruby
-attribute :name, accept: :present?   # "expected to be present?"
-attribute :name, reject: :empty?     # "expected to not be empty?"
-attribute :name, accept: String      # "expected to be a kind of String"
-attribute :name, reject: String      # "expected to not be a kind of String"
+attribute :name, accept: :present?    # "expected to be present?"
+attribute :name, reject: :empty?      # "expected to not be empty?"
+attribute :name, accept: String       # "expected to be a kind of String"
+attribute :name, reject: String       # "expected to not be a kind of String"
 attribute :name, accept: ->(v) { v }  # "is invalid"
 ```
 
-#### `allow_nil:` option
+### `allow_nil:` option
 
 Skip validation when the incoming value is `nil`.
 
@@ -855,11 +736,9 @@ User.new(age: 21).attributes_errors?  # false
 User.new(age: 'x').attributes_errors? # true
 ```
 
-#### `rejection_message:` option
+### `rejection_message:` option
 
-Customize the error message either with a String or with a callable. A callable receives the
-attribute name as its first argument, so the same builder can be reused across attributes (handy
-for i18n).
+Customize the error with a String or a callable. The callable receives the attribute name as its first argument, so the same builder works across attributes (handy for i18n).
 
 ```ruby
 class User
@@ -873,8 +752,7 @@ User.new(name: 1, age: 'x').attributes_errors
 # => { "name" => "must be a string", "age" => "age must be an integer" }
 ```
 
-Callable validators can also expose a `#rejection_message` method themselves, and it will be used
-as the default message for that validator:
+Callable validators can also expose a `#rejection_message` method themselves; it becomes the default message for that validator:
 
 ```ruby
 class FilledString
@@ -894,10 +772,9 @@ class User
 end
 ```
 
-#### Strict mode (`accept: :strict`)
+### Strict mode (`accept: :strict`)
 
-Use `Micro::Attributes.with(accept: :strict)` to raise as soon as any attribute is rejected,
-instead of collecting errors silently.
+Use `Micro::Attributes.with(accept: :strict)` to raise as soon as any attribute is rejected, instead of collecting errors silently.
 
 ```ruby
 class User
@@ -914,15 +791,11 @@ User.new(age: 'x', name: nil)
 # * :name is invalid
 ```
 
-#### Interaction with other features
+### Interaction with other features
 
-- Validation runs **after** the default value resolution, so defaults are validated like any
-  regular value.
-- When combined with the [ActiveModel::Validation extension](#activemodelvalidation-extension),
-  the `:accept` checks run first; AM validations only run if every attribute is accepted.
-- `accept:` plays nicely with [`freeze:`](#freezing-attribute-values-freeze) and
-  [`private:`/`protected:`](#attribute-visibility-private-protected). See the combined example
-  below.
+- Validation runs **after** default-value resolution, so defaults are validated like any regular value.
+- Combined with the [ActiveModel validations extension](#activemodel-validations-extension), the `:accept` checks run first; AM validations only run if every attribute is accepted.
+- `accept:` plays nicely with [`freeze:`](#freezing-values-freeze) and [`private:` / `protected:`](#visibility-private-protected):
 
 ```ruby
 require 'digest'
@@ -932,10 +805,13 @@ class User::SignUpParams
 
   TrimString = ->(value) { String(value).strip }
 
-  attribute  :email,                                              default: TrimString,
-             accept: ->(s) { s =~ /\A.+@.+\..+\z/ }, freeze: :after_dup
-  attributes :password, :password_confirmation, default: TrimString,
-             reject: :empty?, private: true
+  attribute  :email, accept: ->(s) { s =~ /\A.+@.+\..+\z/ },
+                     default: TrimString,
+                     freeze: :after_dup
+
+  attributes :password, :password_confirmation, reject: :empty?,
+                                                default: TrimString,
+                                                private: true
 
   def password_digest
     Digest::SHA256.hexdigest(password) if password == password_confirmation
@@ -943,15 +819,13 @@ class User::SignUpParams
 end
 ```
 
-[⬆️ Back to Top](#table-of-contents-)
+## ActiveModel validations extension
 
-### `ActiveModel::Validation` extension
-
-If your application uses ActiveModel as a dependency (like a regular Rails app). You will be enabled to use the `activemodel_validations` extension.
+If your application uses ActiveModel (e.g. a regular Rails app), enable the `activemodel_validations` extension.
 
 ```ruby
 class Job
-  include Micro::Attributes.with(:activemodel_validations)
+  include Micro::Attributes.with(active_model: :validations)
 
   attribute :id
   attribute :state, default: 'sleeping'
@@ -962,21 +836,18 @@ end
 Job.new({}) # ActiveModel::StrictValidationFailed (Id can't be blank)
 
 job = Job.new(id: 1)
-
 job.id    # 1
-job.state # 'sleeping'
+job.state # "sleeping"
 ```
 
-#### `.attribute()` options
-
-You can use the `validate` or `validates` options to define your attributes. e.g.
+You can also pass `validate:` / `validates:` directly on `attribute`:
 
 ```ruby
 class Job
   include Micro::Attributes.with(:activemodel_validations)
 
-  attribute :id, validates: { presence: true }
-  attribute :state, validate: :must_be_a_filled_string
+  attribute :id,    validates: { presence: true }
+  attribute :state, validate:  :must_be_a_filled_string
 
   def must_be_a_filled_string
     return if state.is_a?(String) && state.present?
@@ -986,11 +857,9 @@ class Job
 end
 ```
 
-[⬆️ Back to Top](#table-of-contents-)
-
-### Diff extension
+## Diff extension
 
-Provides a way to track changes in your object attributes.
+Tracks changes between two instances.
 
 ```ruby
 require 'securerandom'
@@ -1002,167 +871,307 @@ class Job
   attribute :state, default: 'sleeping'
 end
 
-job = Job.new(id: SecureRandom.uuid())
+job         = Job.new(id: SecureRandom.uuid)
+job_running = job.with_attribute(:state, 'running')
 
-job.id    # A random UUID generated from SecureRandom.uuid(). e.g: 'e68bcc74-b91c-45c2-a904-12f1298cc60e'
-job.state # 'sleeping'
+job.state         # "sleeping"
+job_running.state # "running"
 
-job_running = job.with_attribute(:state, 'running')
+changes = job.diff_attributes(job_running)
+
+changes.present?              # true
+changes.blank?                # false
+changes.empty?                # false
 
-job_running.state # 'running'
+changes.changed?              # true
+changes.changed?(:id)         # false
+changes.changed?(:state)      # true
+changes.changed?(:state, from: 'sleeping', to: 'running') # true
 
-job_changes = job.diff_attributes(job_running)
+changes.differences # {'state'=> {'from' => 'sleeping', 'to' => 'running'}}
+```
+
+## Keys as Symbol extension
+
+Disables indifferent access; all keys are symbols.
+
+The default mode stores everything as strings for indifferent access. `:keys_as_symbol` skips that string allocation, lowering memory pressure and GC churn — at the cost of requiring you to use symbols consistently for set/access.
+
+```ruby
+class Job
+  include Micro::Attributes.with(:initialize, :keys_as_symbol)
 
-#-----------------------------#
-# #present?, #blank?, #empty? #
-#-----------------------------#
+  attribute :id
+  attribute :state, default: 'sleeping'
+end
 
-job_changes.present? # true
-job_changes.blank?   # false
-job_changes.empty?   # false
+job = Job.new(id: 1)
 
-#-----------#
-# #changed? #
-#-----------#
-job_changes.changed? # true
+job.attributes # {:id => 1, :state => "sleeping"}
 
-job_changes.changed?(:id)    # false
+job.attribute?(:id)  # true
+job.attribute?('id') # false
 
-job_changes.changed?(:state) # true
-job_changes.changed?(:state, from: 'sleeping', to: 'running') # true
+job.attribute(:id)   # 1
+job.attribute('id')  # nil
 
-#----------------#
-# #differences() #
-#----------------#
-job_changes.differences # {'state'=> {'from' => 'sleeping', 'to' => 'running'}}
+job.attribute!(:id)  # 1
+job.attribute!('id') # NameError (undefined attribute `id)
 ```
 
-[⬆️ Back to Top](#table-of-contents-)
+This extension also makes the [Diff extension](#diff-extension) symbol-only (arguments and outputs).
+
+[⬆️ Back to top](#-attributes)
+
+# Composition
+
+Every `Micro::Attributes` class — whether you reach for `include Micro::Attributes.with(...)`, the [`Micro::Attributes.new`](#microattributesnew) factory, or just `include Micro::Attributes` — composes recursively:
 
-### Initialize extension
+- `attribute :foo, accept: SomeMicroAttributesClass` automatically coerces a hash to that class.
+- `attribute :foo do ... end` defines an anonymous nested class inline; the inline class inherits the outer's feature mix.
+- Nested-attribute errors bubble up as `'is invalid'` markers, while the leaf retains the full rejection message. The same applies to ActiveModel validations.
 
-1. Creates a constructor to assign the attributes.
-2. Add methods to build new instances when some data was assigned.
+There's no `Micro::Entity` wrapper — composition lives in `Micro::Attributes` itself. Every combination of features is covered by `test/micro/attributes/composition_matrix_test.rb`, `with_matrix_test.rb`, and `projection_matrix_test.rb`.
+
+## `Micro::Attributes.new`
+
+A `Struct.new`-style factory that returns a fresh class wired with the requested features. The preset is `{ initialize: true, accept: true }` — override per-key by passing `false` (off), `true` (on), or a variant symbol (`:strict`):
 
 ```ruby
-class Job
-  include Micro::Attributes.with(:initialize)
+User = Micro::Attributes.new do
+  attribute :name, accept: String
+  attribute :age,  accept: Numeric
+end
+
+user = User.new(name: 'Rodrigo', age: 34)
+user.name # "Rodrigo"
+
+bad = User.new(name: :rodrigo, age: '34')
+bad.attributes_errors
+# {
+#   "name" => "expected to be a kind of String",
+#   "age"  => "expected to be a kind of Numeric"
+# }
+```
+
+### Enabling extensions
+
+The factory accepts every key the [hash-style `Micro::Attributes.with(...)`](#picking-a-combination) accepts. Drop in any combination:
+
+```ruby
+# Add Diff on top of the preset:
+Counter = Micro::Attributes.new(diff: true) do
+  attribute :n
+end
+
+a = Counter.new(n: 1)
+b = Counter.new(n: 2)
+a.diff_attributes(b).changed?(:n) # true
 
-  attributes :id, :state
+# Upgrade Initialize and/or Accept to :strict:
+Strict = Micro::Attributes.new(initialize: :strict, accept: :strict) do
+  attribute :n, accept: Integer
 end
 
-job_null = Job.new({})
+Strict.new({})        # ArgumentError: missing keyword: :n
+Strict.new(n: 'x')    # ArgumentError: One or more attributes were rejected. ...
 
-job.id    # nil
-job.state # nil
+# Symbol-keyed storage:
+Sym = Micro::Attributes.new(keys_as: :symbol) do
+  attribute :n
+end
+Sym.new(n: 1).attributes # { n: 1 }
 
-job = Job.new(id: 1, state: 'sleeping')
+# ActiveModel:
+Person = Micro::Attributes.new(active_model: :validations) do
+  attribute :name, validates: { presence: true }
+end
+Person.new(name: nil).valid?               # false
+Person.new(name: nil).errors.full_messages # ["Name can't be blank"]
+
+# All together:
+StrictPerson = Micro::Attributes.new(
+  initialize:   :strict,
+  accept:       true,
+  diff:         true,
+  keys_as:      :symbol,
+  active_model: :validations
+) do
+  attribute :name, accept: String, validates: { presence: true }
+  attribute :age,  accept: Numeric
+end
 
-job.id    # 1
-job.state # 'sleeping'
+StrictPerson.new(name: 'X') # ArgumentError: missing keyword: :age
+```
+
+Each key is overridable per-call: the preset is `{ initialize: true, accept: true }`, so passing `accept: false` (or `nil`) opts out of `:accept` and the returned class has no `attributes_errors` surface. `initialize:` must resolve to `true` or `:strict` — passing `false` raises, because a factory-built class without a hash constructor is almost always a mistake.
+
+## Nested attributes via `accept:`
 
-##############################################
-# Assigning new values to get a new instance #
-##############################################
+When `accept:` is another class that includes `Micro::Attributes` **and has `:initialize`**, hashes assigned to that attribute are auto-coerced into an instance of the target class. Already-built instances pass through unchanged. If the target lacks `:initialize` (you provide your own constructor), the hash passes through and the standard accept check applies — no auto-coercion.
 
-#-------------------#
-# #with_attribute() #
-#-------------------#
+```ruby
+Address = Micro::Attributes.new do
+  attribute :city,   accept: String
+  attribute :postal, accept: String
+end
 
-new_job = job.with_attribute(:state, 'running')
+Profile = Micro::Attributes.new do
+  attribute :name,    accept: String
+  attribute :address, accept: Address
+end
 
-new_job.id          # 1
-new_job.state       # running
-new_job.equal?(job) # false
+profile = Profile.new(name: 'Rodrigo', address: { city: 'Rio', postal: '20000-000' })
 
-#--------------------#
-# #with_attributes() #
-#--------------------#
-#
-# Use it to assign multiple attributes
+profile.address.class # Address
+profile.address.city  # "Rio"
 
-other_job = job.with_attributes(id: 2, state: 'killed')
+# Already-built instances pass through:
+addr    = Address.new(city: 'Rio', postal: '20000-000')
+profile = Profile.new(name: 'Rodrigo', address: addr)
 
-other_job.id          # 2
-other_job.state       # killed
-other_job.equal?(job) # false
+profile.address.equal?(addr) # true
 ```
 
-[⬆️ Back to Top](#table-of-contents-)
+> **Note:** error surfacing through `attributes_errors?` / `attributes_errors` (and the deep-bubble marker) requires the **parent** to also include `:accept`. A parent without `:accept` will still coerce hashes into child instances, but it has no `attributes_errors` machinery to mirror descendant invalidity — `parent.child.attributes_errors?` may be true while the parent looks clean. Walk the tree explicitly in that case, or include `:accept` on the parent.
 
-#### Strict mode
+## Defining nested attributes inline (block form)
 
-1. Creates a constructor to assign the attributes.
-2. Adds methods to build new instances when some data was assigned.
-3. **Forbids missing keywords**.
+`attribute` accepts a block. The block defines an anonymous nested class with the **same feature mix** as the host — strict / symbol-keys / AM all propagate:
 
 ```ruby
-class Job
-  include Micro::Attributes.with(initialize: :strict)
+Order = Micro::Attributes.new do
+  attribute :id, accept: Integer
 
-  attributes :id, :state
+  attribute :customer do
+    attribute :name,  accept: String
+    attribute :email, accept: String
+  end
 end
-#-----------------------------------------------------------------------#
-# The strict initialize mode will require all the keys when initialize. #
-#-----------------------------------------------------------------------#
 
-Job.new({})
+order = Order.new(id: 1, customer: { name: 'Rodrigo', email: 'rodrigo@example.com' })
+order.customer.name # "Rodrigo"
+```
+
+The inline class uses the host's `Micro::Attributes.with(...)` module, so a `keys_as: :symbol` host yields a symbol-keyed inline child, an `initialize: :strict` host yields a strict inline child, and so on.
+
+### Per-block extensions
 
-# The code above will raise:
-# ArgumentError (missing keywords: :id, :state)
+The block also accepts the `with(...)` class macro — the same one used to layer features at the top of a class body. Calling it as the first thing inside the block layers **additional** features onto just that inline child, on top of whatever the host already provides:
 
-#---------------------------#
-# Samples passing some data #
-#---------------------------#
+```ruby
+class Order
+  include Micro::Attributes.with(:initialize, :accept)
 
-job_null = Job.new(id: nil, state: nil)
+  attribute :customer do
+    with diff: true, active_model: :validations
 
-job.id    # nil
-job.state # nil
+    attribute :name, accept: String, validates: { presence: true }
+  end
 
-job = Job.new(id: 1, state: 'sleeping')
+  attribute :address do          # ← this one stays minimal
+    attribute :city, accept: String
+  end
+end
 
-job.id    # 1
-job.state # 'sleeping'
+order = Order.new(
+  customer: { name: 'Rodrigo' },
+  address:  { city: 'Lisbon' }
+)
+
+order.customer.respond_to?(:diff_attributes) # true   — Diff layered just here
+order.customer.valid?                        # true
+order.address.respond_to?(:diff_attributes)  # false  — sibling block did not bleed across
 ```
 
-> **Note**: This extension works like the `initialize` extension. So, look at its section to understand all of the other features.
+Sibling blocks are independent — `with(...)` only affects the block it appears in. Positional symbols work too (`with :diff, :keys_as_symbol`), mirroring the [hash-style options](#picking-a-combination).
 
-[⬆️ Back to Top](#table-of-contents-)
+You can only **add** features inside a block, not remove ones the host already enabled. If a specific nested entity needs to opt OUT of an extension the host has, define it as a separate class via [`Micro::Attributes.new(...)`](#microattributesnew) (or `include Micro::Attributes.with(...)`) and reference it through `accept: TheOtherClass` instead of using the block form.
 
-### Keys as symbol extension
+## Deep nesting & validation bubbling
 
-Disables the indifferent access requiring the declaration/usage of the attributes as symbols.
+Both forms (class-based via `accept:` and block-form) compose recursively to any depth. Each level carries its own `attributes_errors` / `errors`; any descendant invalidity is **mirrored** up the chain as a `'is invalid'` marker while the leaf retains the original message.
 
-The advantage of this extension over the default behavior is because it avoids an unnecessary allocation in memory of strings. All the keys are transformed into strings in the indifferent access mode, but, with this extension, this typecasting will be avoided. So, it has a better performance and reduces the usage of memory/Garbage collector, but gives for you the responsibility to always use symbols to set/access the attributes.
+### Accept-error bubbling (no ActiveModel needed)
 
 ```ruby
-class Job
-  include Micro::Attributes.with(:initialize, :keys_as_symbol)
+City    = Micro::Attributes.new { attribute :name,    accept: String }
+Address = Micro::Attributes.new { attribute :city,    accept: City    }
+Profile = Micro::Attributes.new { attribute :address, accept: Address }
 
-  attribute :id
-  attribute :state, default: 'sleeping'
+profile = Profile.new(address: { city: { name: 42 } })
+
+# Leaf has the detail
+profile.address.city.attributes_errors  # {"name" => "expected to be a kind of String"}
+
+# Every ancestor mirrors the invalidity
+profile.attributes_errors?              # true
+profile.attributes_errors               # {"address" => "is invalid"}
+profile.address.attributes_errors       # {"city" => "is invalid"}
+```
+
+### ActiveModel deep validation
+
+When `active_model: :validations` (or `:activemodel_validations` positional) is in the feature mix, `parent.valid?` reflects deep descendant invalidity automatically:
+
+```ruby
+Leaf = Micro::Attributes.new(active_model: :validations) do
+  attribute :name, accept: String, validates: { presence: true }
 end
 
-job = Job.new(id: 1)
+Mid = Micro::Attributes.new(active_model: :validations) do
+  attribute :leaf, accept: Leaf
+end
 
-job.attributes # {:id => 1, :state => "sleeping"}
+Root = Micro::Attributes.new(active_model: :validations) do
+  attribute :mid, accept: Mid
+end
 
-job.attribute?(:id) # true
-job.attribute?('id') # false
+root = Root.new(mid: { leaf: { name: '' } })
 
-job.attribute(:id) # 1
-job.attribute('id') # nil
+root.valid?                  # false   — bubbled up
+root.errors[:mid]            # ["is invalid"]
+root.mid.errors[:leaf]       # ["is invalid"]
+root.mid.leaf.errors[:name]  # ["can't be blank"]   ← detail at the leaf
+```
 
-job.attribute!(:id) # 1
-job.attribute!('id') # NameError (undefined attribute `id)
+Mixed trees work too — if a child has no AM, the validator falls back to checking its `attributes_errors?`:
+
+```ruby
+AcceptLeaf = Micro::Attributes.new do                      # no AM
+  attribute :name, accept: String
+end
+
+AMRoot = Micro::Attributes.new(active_model: :validations) do
+  attribute :leaf, accept: AcceptLeaf
+end
+
+AMRoot.new(leaf: { name: 42 }).valid?    # false — accept-error on the leaf bubbles to AM on root
 ```
 
-As you could see in the previous example only symbols will work to do something with the attributes.
+The contract: **detail at the leaf, marker at every ancestor.** Walk the tree (`obj.mid.leaf.attributes_errors`) for the message; use `obj.attributes_errors?` / `obj.valid?` at the top to gate flow.
+
+[⬆️ Back to top](#-attributes)
+
+# Notes
+
+## What "immutable" means here (and thread safety)
+
+`u-attributes` provides **structural** immutability: there are no setters, and `#with_attribute(s)` returns a new instance instead of mutating the old one. The stored values themselves are **not** deep-frozen by default — if you assign a mutable object (an `Array`, `Hash`, custom class instance), callers that share that reference can still mutate it in place.
+
+For full immutability of contained values, combine `freeze:` (which freezes the stored value after assignment) with already-frozen inputs, or freeze nested structures yourself before assignment. The `:after_dup` / `:after_clone` modes give you a safe boundary — the copy is frozen, the original isn't.
+
+This means instances are safe to share across threads only to the extent that the values they hold are also safe to share.
+
+## Unknown keys in `extract_attributes_from`
+
+`extract_attributes_from(source)` reads only names that the class declared via `attribute` / `attributes`. Any extra keys on a hash source — or extra methods on an object source — are silently ignored. No warning, no error.
+
+## Migrating from 2.x
 
-This extension also changes the `diff extension` making everything (arguments, outputs) working only with symbols.
+The 2.x line ([README](https://github.com/serradura/u-attributes/blob/v2.x/README.md)) supported Ruby `>= 2.2` and a broader `activemodel` range. 3.x raises the floors (Ruby `>= 2.7`, `activemodel >= 6.0`) and reshapes the extension API toward the `Micro::Attributes.with(...)` form documented here. See [`CHANGELOG.md`](./CHANGELOG.md) for the full list of changes.
 
-[⬆️ Back to Top](#table-of-contents-)
+[⬆️ Back to top](#-attributes)
 
 # Development
 
@@ -1180,4 +1189,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 # Code of Conduct
 
-Everyone interacting in the Micro::Attributes project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/serradura/u-attributes/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Micro::Attributes project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/serradura/u-attributes/blob/main/CODE_OF_CONDUCT.md).