hibiki 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68d12a0c95c1bc55b68b6fe1377a2ca6bcd9bf9116a2ced78de0d6748dd40abb
-  data.tar.gz: 5288e41ed33db0976d15b17bac1aac827344207841921467b25c0e9eef76da8d
+  metadata.gz: 62668f45023a6d59c07b6f414b0c6ec50a7ff264b5dc9d2b6ad0bedfec9510cc
+  data.tar.gz: 9391c0a9b3865c61a0c6cc7f2463e3a377cac91b89820fd3cb3c34dffcc52ddc
 SHA512:
-  metadata.gz: c36067422510591e66e4d244d4a27dd1ae0c6c9f6f33ef4e8d82f340a12b5f7ec456c272855ee8c425df9bdb2f98f8062899169b2c97155f976e076aaf8431bc
-  data.tar.gz: d69a165a500e5355709d98c079f0b026dfe2eea9f09de14b20378513274f02c9f8790021992a8ce9a4e738bd4d5a8feeb89e0e9b3bc3418eb56394edd4579571
+  metadata.gz: e425aa81829367bd15d732dd2dd3a2f7fe854199a03df742c4d3e764f0a01e756fc2af81c8d14582630884fc4314d98b3750851554c9da34c0b3b9825da1bf45
+  data.tar.gz: dd3e43c2bb9e9f6b399feb2da484913837646ec81bb9d5d55c2f41c31883270e2996d062a59c01497376f10005c49c76c5fa54a2ba0eac683afdea15d33f9a75

data/CHANGELOG.md

@@ -7,7 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.1.0] - TBD
+## [0.3.0] - 2026-08-09
+
+### Added
+
+- **`equals:` — a per-signal equality override** on `State` and `Derived`, and
+  passed through by the `state`/`derived` helpers in `Hibiki::DSL` and
+  `Hibiki::Reactive`. Solid's `createSignal(value, { equals })` shape:
+  omitted/`nil` keeps `==`; a callable is a custom comparator, called with
+  `(prev, next)`, truthy meaning "unchanged"; `equals: false` means every write
+  notifies. The override is honored at both places equality guards the graph —
+  the write gate (`State#value=`) and the effect equality gate at the batch
+  flush (new `Trackable#changed_from?`, consulted by
+  `Observer#sources_changed?`). Signals that don't pass `equals:` behave
+  exactly as before.
+
+## [0.2.0] - 2026-07-29
+
+### Changed
+
+- **BREAKING: effects re-run only when a value they read actually changed.**
+  Every read now remembers the value it saw, and at the batch flush an effect
+  compares each of its dependencies against what it last read; if everything
+  compares `==`, the effect does not run and its scheduler is not called.
+  Svelte's `$derived` compares, and now so does Hibiki — on the reading side,
+  because a derived has already notified its subscribers by the time it knows
+  its new value. Measured motivation: a write that rippled through a derived to
+  a structurally identical value pushed a 159 KB re-render with nothing
+  changed anywhere.
+
+  Two behaviour changes to be aware of:
+
+  - an effect kept for a side effect *per write* (a heartbeat, a log line, a
+    counter) must read the value that genuinely changes rather than a derived
+    summary that often doesn't;
+  - a derived that returns the same object it mutated compares equal to itself,
+    so the gate swallows the update — return a new object. `Effect#run` still
+    bypasses the gate entirely.
+
+  A batch that nets to no change (`batch { a.value = 2; a.value = 1 }`) also
+  stops re-running effects. `Derived`'s laziness is unchanged: it still
+  recomputes on read, never on write.
+
+## [0.1.0] - 2026-07-18
 
 ### Added
 

data/README.md

@@ -26,6 +26,9 @@ include Hibiki::DSL
 
 x = state(0)
 y = derived { x.value + 1 }
+
+x.value = 10
+y.value # => 11
 ```
 
 Or if you wish to avoid using DSL:
@@ -43,7 +46,7 @@ y.value # => 11
 
 ### The three primitives
 
-**`state(v)`** — a writable signal. Reading `.value` registers a dependency; writing notifies subscribers. Writing an `==`-equal value is a no-op.
+**`state(v)`** — a writable signal. Reading `.value` registers a dependency; writing notifies subscribers. Writing an `==`-equal value is a no-op — overridable per signal with `equals:`; see [Custom equality](https://planetaska.github.io/hibiki/advanced-usage/#custom-equality-equals).
 
 ```ruby
 counter = state(0)
@@ -51,14 +54,14 @@ counter.value += 1
 counter.update { it + 1 } # in-place sugar
 ```
 
-**`derived { }`** — a lazy computed signal. It recomputes on read when marked dirty, never on write, and caches its value until a dependency changes.
+**`derived { }`** — a lazy computed signal. It recomputes on read when marked dirty (when any state it depends on changes), never on write, and caches its value until a dependency changes.
 
 ```ruby
 doubled = derived { counter.value * 2 }
 doubled.value # => 4
 ```
 
-**`effect { }`** — an eager side effect. It runs immediately and re-runs whenever a dependency changes.
+**`effect { }`** — an eager side effect. It *runs immediately* and re-runs whenever a dependency (any state inside the effect block) changes.
 
 ```ruby
 name = state("world")
@@ -68,26 +71,6 @@ effect { puts "hello, #{name.value}!" } # prints "hello, world!"
 name.value = "Ruby"                     # prints "hello, Ruby!"
 ```
 
-### Untracked reads
-
-Sometimes an effect should *sample* a signal without depending on it.
-`Hibiki.untrack { }` suppresses dependency registration for a block, and
-`#peek` is the per-signal shorthand — the classic use is read-modify-write,
-where an effect must not depend on the signal it writes:
-
-```ruby
-count = state(0)
-history = state([])
-
-# Log every count change — without peek, writing history would re-trigger
-# this effect forever (it would depend on its own output).
-effect { history.value = history.peek + [count.value] }
-```
-
-A dirty derived still recomputes on `peek`; only the reader's subscription is
-skipped. Signals also respond to `#call`, mirroring Solid's
-signals-as-getter-functions: `count.call` (or `count.()`) reads and registers.
-
 ### Dynamic dependencies
 
 Dependencies are re-collected on every recompute, so conditional reads work:
@@ -104,42 +87,9 @@ flag.value = false
 picked.value        # => "B2" (deps re-collected)
 ```
 
-### Lifecycle: `root` and `on_cleanup`
-
-Effects created while another effect runs are *owned* by it and disposed
-automatically when the owner re-runs or is disposed. For everything else
-there is `Hibiki.root` (Solid's `createRoot`): an ownership scope you tear
-down yourself — the anchor for long-lived graphs (a session, a connection)
-whose teardown is an external event, not a rerun.
-
-`Hibiki.on_cleanup` (Solid's `onCleanup`) registers teardown on the owning
-effect or root; it runs before each re-run and on dispose — the place to
-release timers, sockets, subscriptions an effect sets up:
-
-```ruby
-interval = state(1)
-
-ticker = Hibiki.root do
-  effect do
-    timer = start_timer(every: interval.value)
-    Hibiki.on_cleanup { timer.cancel } # runs before each re-run, and on dispose
-  end
-end
-
-interval.value = 5 # old timer cancelled, new one started
-ticker.dispose     # tears down every effect in the scope, cleanups included
-```
-
-A root's block runs untracked, and a root created inside an effect is *not*
-adopted by it — it deliberately escapes the automatic owner tree, so its
-lifetime is exactly `Hibiki.root` … `root.dispose`. Individual effects can
-still be disposed directly with `Effect#dispose`.
-
 ### Class-based reactivity
 
-Svelte 5 allows `$state`/`$derived`/`$effect` as class fields; `Hibiki::Reactive`
-is the Ruby analogue. Declare signals with class macros and use them as plain
-attributes — no `.value` at usage sites:
+Svelte 5 allows `$state` / `$derived` / `$effect` as class fields; `Hibiki::Reactive` is the Ruby analogue. Declare signals with class macros and use them as plain attributes — no more `.value` in code:
 
 ```ruby
 class Counter
@@ -158,46 +108,15 @@ counter.increment      # prints "count is now 1"
 counter.doubled        # => 2
 ```
 
-Signals are per-instance and created lazily; subclasses inherit all
-declarations. Use the block form for mutable defaults (a positional default
-is one shared object, the same gotcha as Rails attribute defaults).
-
-Effect lifecycle: an instance created *inside* a running effect is adopted by
-the owner tree and cleaned up automatically when that owner re-runs or is
-disposed. For long-lived instances whose effects read signals *outside* the
-instance, call `#dispose` — effects that only read the instance's own signals
-form a self-contained island that garbage-collects with it.
-
-### Why no transparent signals?
-
-Two designs were evaluated and rejected, so they don't need relitigating:
-
-- **Transparent value wrappers** (`method_missing` forwarding to `.value`):
-  Ruby object truthiness cannot be overridden, so `if flag` on a wrapper is
-  always true — it silently breaks conditionals, the exact thing dynamic
-  dependency tracking is best at. `nil?` and `==` lie similarly.
-- **A `reactive do ... end` block DSL**: Ruby has no hook for bare local
-  variable reads or writes, so writes need `self.x =` anyway — at which point
-  a class (above) wears the same design better.
-
-The full walkthrough with examples lives in
-[docs-md/why-no-transparent-signals.md](docs-md/why-no-transparent-signals.md).
+Signals are per-instance and created lazily; subclasses inherit all declarations. Use the block form for mutable defaults — a positional default is one object shared by every instance; see [Mutable state defaults](https://planetaska.github.io/hibiki/mutable-defaults/) for the details.
 
 ## Documentation
 
-Browsable documentation site: <https://planetaska.github.io/hibiki/>
-
-More detail in [docs-md/](docs-md/):
+Full documentation: <https://planetaska.github.io/hibiki/>
 
-- [Why no transparent signals?](docs-md/why-no-transparent-signals.md) — the two
-  rejected transparency designs, with the failure cases spelled out.
-- [Threading model](docs-md/threading-model.md) — fiber-confined bookkeeping,
-  what is and isn't isolated across threads, fibers, and Ractors.
-- [Status & limitations](docs-md/status-and-limitations.md) — what the signal
-  core already guarantees.
-- [Fragment-level render effects](docs-md/fragment-level-render-effects.md) —
-  a deferred design note: collapsing per-fragment partials/components into
-  methods, each wrapped in its own effect.
+- [Guide](https://planetaska.github.io/hibiki/introduction/) — getting started, class-based reactivity, advanced usage
+- [Rails](https://planetaska.github.io/hibiki/rails-introduction/) — the `hibiki_rails` and `hibiki_phlex` integration, generators, CRUD scaffolding
+- [Reference](https://planetaska.github.io/hibiki/threading-model/) — threading model, lifecycle in detail, status and limitations
 
 ## Development
 

data/lib/hibiki/derived.rb

@@ -6,8 +6,12 @@ module Hibiki
     include Trackable # observed by downstream deriveds/effects
     include Observer  # observes its own dependencies
 
-    def initialize(&block)
+    # equals: per-signal equality (Solid's createMemo takes it too). A derived
+    # has no write gate, so it matters only at the flush gate — observers ask
+    # changed_from?, which consults it (see Trackable).
+    def initialize(equals: nil, &block)
       @block = block
+      @equals = equals
       @dirty = true
     end
 

data/lib/hibiki/dsl.rb

@@ -5,8 +5,8 @@ module Hibiki
   # Opt-in: `include Hibiki::DSL` where you want the bare helpers.
   # The gem never includes it for you (no polluting Object/main).
   module DSL
-    def state(value) = State.new(value)
-    def derived(&) = Derived.new(&)
+    def state(value, equals: nil) = State.new(value, equals:)
+    def derived(equals: nil, &) = Derived.new(equals:, &)
     def effect(scheduler: nil, &) = Effect.new(scheduler:, &)
     def batch(&)   = Hibiki.batch(&)
     def root(&)    = Hibiki.root(&)

data/lib/hibiki/effect.rb

@@ -39,9 +39,21 @@ module Hibiki
     # re-run is handed to it right where it would have happened — after the
     # batch dedup, so the flush's error isolation covers a raising scheduler
     # too, and N batched writes mean one scheduler call.
+    #
+    # Past the batching? check we are at the flush, which is where the equality
+    # gate belongs: every write in the wave has landed, so asking the sources
+    # whether anything changed reads a consistent graph (a diamond validates
+    # once, against both legs). Nothing changed means nothing to do — not even
+    # a scheduler call, so a debounced broadcast never fires for a no-op.
+    #
+    # own(self) because validation may recompute a derived whose block
+    # registers an on_cleanup or creates an effect: this effect's own run is
+    # where that would otherwise have landed. Deriveds are values, not owners —
+    # a block with side effects was already at the mercy of whoever reads first.
     def invalidate
       return if @disposed
       return Hibiki.schedule(self) if Hibiki.batching?
+      return unless Hibiki.own(self) { sources_changed? }
       return @scheduler.call(self) if @scheduler
 
       run

data/lib/hibiki/reactive.rb

@@ -34,16 +34,16 @@ module Hibiki
       # instance, instance_exec'd, and untracked: first touch may happen
       # inside some effect's tracking window, and a default that reads other
       # signals must not subscribe that outer observer.
-      def state(name, default = nil, &default_block)
+      def state(name, default = nil, equals: nil, &default_block)
         init = proc do
-          State.new(default_block ? Hibiki.untrack { instance_exec(&default_block) } : default)
+          State.new(default_block ? Hibiki.untrack { instance_exec(&default_block) } : default, equals:)
         end
         define_method(name) { __hibiki_signal(name, init).value }
         define_method(:"#{name}=") { |new_value| __hibiki_signal(name, init).value = new_value }
       end
 
-      def derived(name, &)
-        init = proc { Derived.new { instance_exec(&) } }
+      def derived(name, equals: nil, &)
+        init = proc { Derived.new(equals:) { instance_exec(&) } }
         define_method(name) { __hibiki_signal(name, init).value }
       end
 

data/lib/hibiki/state.rb

@@ -5,8 +5,11 @@ module Hibiki
   class State
     include Trackable
 
-    def initialize(value)
+    # equals: per-signal equality (Solid's createSignal(value, { equals })).
+    # nil → `==`; false → always notify; callable → comparator(prev, next).
+    def initialize(value, equals: nil)
       @value = value
+      @equals = equals
     end
 
     def value
@@ -22,7 +25,14 @@ module Hibiki
     def call = value
 
     def value=(new_value)
-      return if new_value == @value
+      # The write gate: the signal's equality decides whether this write is a
+      # no-op. Its twin is the flush gate, Trackable#changed_from? — keep them
+      # answering the same way.
+      case @equals
+      when nil then return if new_value == @value
+      when false then nil # always notify
+      else return if @equals.call(@value, new_value)
+      end
 
       @value = new_value
       # Solid wraps every write in runUpdates; mirroring that, an unbatched

data/lib/hibiki/tracking.rb

@@ -60,16 +60,36 @@ module Hibiki
     # Called on every read: if someone reactive is currently computing,
     # they now depend on us — record both directions of the edge, so the
     # observer can sever it before its next rerun.
+    #
+    # The VALUE travels with the edge: an observer that remembers what it saw
+    # can decide later whether anything it reads actually changed (Svelte's
+    # $derived compares; see Observer#sources_changed?). `peek` is the
+    # documented read-without-an-edge, and we're already clean here — a
+    # Derived recomputes before it registers — so it costs a cache read.
     def register_dependency
       observer = Hibiki.current_observer
       return unless observer
 
       subscribers << observer
-      observer.add_source(self)
+      observer.add_source(self, peek)
     end
 
     def unsubscribe(observer) = subscribers.delete(observer)
 
+    # The flush gate's question, answered by the source so its own equality
+    # decides (Solid's `equals` option, on createSignal and createMemo alike):
+    # nil → `==` as always, false → never equal (every write notifies),
+    # callable → comparator(prev, next). Both gates consult the same @equals —
+    # a comparator honored on write but not at flush would let the batch
+    # flush silently swallow the very change the write announced.
+    def changed_from?(seen)
+      case @equals
+      when nil then peek != seen
+      when false then true
+      else !@equals.call(seen, peek)
+      end
+    end
+
     def notify
       # dup: invalidation may mutate the set while we iterate
       subscribers.dup.each(&:invalidate)
@@ -77,17 +97,37 @@ module Hibiki
   end
 
   # ---- shared observer behaviour ----------------------------------------------
-  # The reverse edges of Trackable: what an observer read on its last run.
+  # The reverse edges of Trackable: what an observer read on its last run, and
+  # the value each one had when it read it.
   module Observer
-    def sources = (@sources ||= Set.new)
-    def add_source(source) = sources << source
+    # source => the value we saw for it. A Hash rather than a Set because the
+    # remembered value is what makes the equality gate possible; last read in
+    # a run wins, which is the value the run actually acted on.
+    def sources = (@sources ||= {})
+    def add_source(source, seen) = sources[source] = seen
 
     # Solid clears deps before rerun (cleanNode); we mirror that, so stale
     # branches of dynamic deps (flag ? a : b) stop invalidating us.
     def clear_sources
-      sources.each { |source| source.unsubscribe(self) }
+      sources.each_key { |source| source.unsubscribe(self) }
       sources.clear
     end
+
+    # The equality gate, asked at flush time (see Effect#invalidate): did any
+    # value we read actually change? Svelte's $derived compares; we compare on
+    # the observer's side instead of the producer's, because Derived#invalidate
+    # has already notified downstream by the time it knows its new value. The
+    # comparison itself is delegated to each source (changed_from?), so a
+    # per-signal `equals:` is honored here too.
+    #
+    # changed_from?'s `peek` resolves a dirty source without subscribing us to
+    # it — no untrack needed, since a Derived#recompute makes itself the
+    # observer. `any?` short-circuits in the useful direction: sources are in
+    # read order, so a changed first source spares the rest a validation
+    # recompute, and the run recomputes them only if it reads them this time.
+    def sources_changed?
+      sources.any? { |source, seen| source.changed_from?(seen) }
+    end
   end
 
   # ---- shared owner behaviour ---------------------------------------------------

data/lib/hibiki/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hibiki
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hibiki
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - planetaska