docs: add n1_bind_to example and update README for v2.1.0 context-sharing feature (#51)

Author: Copilot

README.md

@@ -55,6 +55,17 @@ Are you not working with [ActiveRecord][5]? N1Loader is ready to be used as stan
 gem 'n1_loader'
 ```
 
+Want lazy, N+1-free loading without explicit preloading? Use `n1_bind_to` to share context across a collection of plain Ruby objects. ([full snippet](examples/n1_bind_to.rb))
+
+```ruby
+users = [User.new, User.new, User.new]
+
+# Bind users to the collection — lazy access is now automatically batched
+users.each { |user| user.n1_bind_to(users) }
+
+users.map(&:optimized_call) # loads all in a single batch, no N+1
+```
+
 ## How to use it?
 
 N1Loader provides DSL that allows you to define N+1 ready loaders that can 
@@ -156,6 +167,7 @@ p User.all.includes(:payments_total).map { |user| user.payments_total(from: from
 - Loader support [arguments](examples/arguments_support.rb)
 - Has [integration](examples/active_record_integration.rb) with [ActiveRecord][5] which makes it brilliant
 - Has [integration](examples/ar_lazy_integration.rb) with [ArLazyPreload][6] which makes it excellent
+- Supports [context sharing](examples/n1_bind_to.rb) for plain Ruby objects without ActiveRecord
 
 ### Feature killer for [ArLazyPreload][6] integration with isolated loaders
 
@@ -168,6 +180,16 @@ Without further ado, please have a look at the [example](examples/ar_lazy_integr
 
 _Spoiler:_ as soon as you have your loader defined, it will be as simple as `Loader.for(element)` to get your data efficiently and without N+1.
 
+### Context sharing for plain Ruby objects with `n1_bind_to`
+
+In [version 2.1.0](CHANGELOG.md#210---20260307) context sharing was added for plain Ruby objects.
+This allows you to get lazy, N+1-free loading without [ActiveRecord][5] or explicit preloading.
+
+By calling `n1_bind_to(collection)` on each element, you bind them to their shared collection.
+When any loader is triggered on a bound element, it automatically batch-loads for the entire collection — and nested loaders propagate the context automatically as well.
+
+Have a look at the [example](examples/n1_bind_to.rb) to see how simple it is.
+
 ## Funding
 
 ### Open Collective Backers

examples/core.rb

@@ -32,8 +32,16 @@ def unoptimized_call
 p users.map(&:unoptimized_call)
 p "Has N+1 #{Service.count == count_before + users.count}"
 
-# Has no N+1
+# Has no N+1 via explicit preloading
 count_before = Service.count
 N1Loader::Preloader.new(users).preload(:optimized_call)
 p users.map(&:optimized_call)
 p "Has no N+1: #{Service.count == count_before + 1}"
+
+users = [User.new, User.new]
+
+# Has no N+1 via n1_bind_to context sharing (see examples/n1_bind_to.rb)
+users.each { |user| user.n1_bind_to(users) }
+count_before = Service.count
+p users.map(&:optimized_call)
+p "Has no N+1: #{Service.count == count_before + 1}"

examples/n1_bind_to.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "n1_loader"
+
+require_relative 'context/service'
+
+# Class that wants to request 3rd party service without N+1
+class User
+  include N1Loader::Loadable
+
+  n1_optimized :optimized_call do |users|
+    data = Service.receive(users)
+
+    users.each_with_index do |user, index|
+      fulfill(user, data[index])
+    end
+  end
+end
+
+users = [User.new, User.new, User.new]
+
+# Without n1_bind_to: each user lazily loads independently causing N+1
+count_before = Service.count
+p users.map(&:optimized_call)
+p "Has N+1: #{Service.count == count_before + users.count}"
+
+users = [User.new, User.new, User.new]
+
+# With n1_bind_to: bind users to the collection so lazy loading is automatically batched
+users.each { |user| user.n1_bind_to(users) }
+
+count_before = Service.count
+p users.map(&:optimized_call)
+p "Has no N+1: #{Service.count == count_before + 1}"