hibiki 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68d12a0c95c1bc55b68b6fe1377a2ca6bcd9bf9116a2ced78de0d6748dd40abb
-  data.tar.gz: 5288e41ed33db0976d15b17bac1aac827344207841921467b25c0e9eef76da8d
+  metadata.gz: d473629248429556ab9410edc059933072d1a6c6f462fd9fa225c25684d45c79
+  data.tar.gz: 025ac97891ad5933eecd82201323f3c329e3dedc392f6407e6004175ee7c316a
 SHA512:
-  metadata.gz: c36067422510591e66e4d244d4a27dd1ae0c6c9f6f33ef4e8d82f340a12b5f7ec456c272855ee8c425df9bdb2f98f8062899169b2c97155f976e076aaf8431bc
-  data.tar.gz: d69a165a500e5355709d98c079f0b026dfe2eea9f09de14b20378513274f02c9f8790021992a8ce9a4e738bd4d5a8feeb89e0e9b3bc3418eb56394edd4579571
+  metadata.gz: 897c70917201523c25cd459fe84ee402cd25a92268729c505fff5109bf4f51e462f69791cc4f3204343d06193983d1f50498d5e0ea6dfadeffd0260721f6fbbb
+  data.tar.gz: 693c6e0cae17d37c3c1b1eeea8b94ee5323ecdf103f89690c34389779c37f426fd49fc4141640e6666ba3d8f1bbd78856a1b6399ec92a166dca307daa8269c59

data/CHANGELOG.md

@@ -7,7 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.1.0] - TBD
+## [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:
@@ -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,13 @@ 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](docs-md/mutable-defaults.md) for the details.
 
 ## Documentation
 
-Browsable documentation site: <https://planetaska.github.io/hibiki/>
-
-More detail in [docs-md/](docs-md/):
+Documentation site: <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.
+More detail in plain markdown: [docs-md/](docs-md/)
 
 ## Development
 

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/tracking.rb

@@ -60,12 +60,18 @@ 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)
@@ -77,17 +83,35 @@ 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.
+    #
+    # `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.peek != 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.2.0"
 end

metadata

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