hibiki 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d473629248429556ab9410edc059933072d1a6c6f462fd9fa225c25684d45c79
-  data.tar.gz: 025ac97891ad5933eecd82201323f3c329e3dedc392f6407e6004175ee7c316a
+  metadata.gz: 62668f45023a6d59c07b6f414b0c6ec50a7ff264b5dc9d2b6ad0bedfec9510cc
+  data.tar.gz: 9391c0a9b3865c61a0c6cc7f2463e3a377cac91b89820fd3cb3c34dffcc52ddc
 SHA512:
-  metadata.gz: 897c70917201523c25cd459fe84ee402cd25a92268729c505fff5109bf4f51e462f69791cc4f3204343d06193983d1f50498d5e0ea6dfadeffd0260721f6fbbb
-  data.tar.gz: 693c6e0cae17d37c3c1b1eeea8b94ee5323ecdf103f89690c34389779c37f426fd49fc4141640e6666ba3d8f1bbd78856a1b6399ec92a166dca307daa8269c59
+  metadata.gz: e425aa81829367bd15d732dd2dd3a2f7fe854199a03df742c4d3e764f0a01e756fc2af81c8d14582630884fc4314d98b3750851554c9da34c0b3b9825da1bf45
+  data.tar.gz: dd3e43c2bb9e9f6b399feb2da484913837646ec81bb9d5d55c2f41c31883270e2996d062a59c01497376f10005c49c76c5fa54a2ba0eac683afdea15d33f9a75

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

data/README.md

@@ -46,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)
@@ -108,13 +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 object shared by every instance; see [Mutable state defaults](docs-md/mutable-defaults.md) for the details.
+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
 
-Documentation site: <https://planetaska.github.io/hibiki/>
+Full documentation: <https://planetaska.github.io/hibiki/>
 
-More detail in plain markdown: [docs-md/](docs-md/)
+- [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/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

@@ -76,6 +76,20 @@ module Hibiki
 
     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)
@@ -102,15 +116,17 @@ module Hibiki
     # 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.
+    # 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.
     #
-    # `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.
+    # 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.peek != seen }
+      sources.any? { |source, seen| source.changed_from?(seen) }
     end
   end
 

data/lib/hibiki/version.rb

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

metadata

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