signalize 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 023d2e474c347003b12bef1210945016175838261a5761dae81cb90d749fe51b
-  data.tar.gz: 04adf75c67d46adf30fabfdf996eea3ef1555678f96189444d32355571c5d12d
+  metadata.gz: a0caca6f4fbd9e03da42b9a5d6774f41cd3a75e0c3531e6a4a856a6db46fda31
+  data.tar.gz: 405900c040ca95a168ab288cdd44d3bbfb563c3513ba34bf17ca4054262591ba
 SHA512:
-  metadata.gz: 1c6cc8aad7188bde45f3c5e535d8a7c9ceb17e0598f35ebe45791cf194b8489e799fb32680c130f4bd3f0c06e399ae900bfa8dd103fd7431fe779856fb1685cc
-  data.tar.gz: e3eacdfae3cecd69c3b17158e4ae5610119d83e778e369479c487a1ac42e88dcb554cb9c3389cf4d1e1689a337f1bab2f0e02230d6a22b59df3b4bb2993069c3
+  metadata.gz: 2620410cdb72ea66cf1a6a9deef3d2d945b9208fd80c3d351a4946f31ae3288302c095420a3c8c4351688bef6fb788c936de5e2aead20e6003ae001d5303290c
+  data.tar.gz: 44c96f16d953c00127df8a21905515e29accdac583117ccd52d7c5f410fe190bc98962c173968bda2f460227745a462fade990aba26a4c4ddbbf55b6f23904b1

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [1.3.0] - 2023-10-04
+
+- Provide `Signalize::Struct`, a struct-like object to hold multiple signals (including computed)
+  (optional via `require "signalize/struct"`)
+
+## [1.2.0] - 2023-10-03
+
+- Add `untracked` method (implements #5)
+- Add `mutation_detected` check for `computed`
+
+Gem now roughly analogous to `@preact/signals-core` v1.5
+
 ## [1.1.0] - 2023-03-25
 
 - Provide better signal/computed inspect strings (fixes #1)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    signalize (1.1.0)
+    signalize (1.3.0)
       concurrent-ruby (~> 1.2)
 
 GEM

data/README.md

@@ -25,7 +25,7 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-Signalize's public API consists of four methods (you can think of them almost like functions): `signal`, `computed`, `effect`, and `batch`.
+Signalize's public API consists of five methods (you can think of them almost like functions): `signal`, `untracked`, `computed`, `effect`, and `batch`.
 
 ### `signal(initial_value)`
 
@@ -54,6 +54,27 @@ counter = signal(0)
 counter.value += 1
 ```
 
+### `untracked { }`
+
+In case when you're receiving a callback that can read some signals, but you don't want to subscribe to them, you can use `untracked` to prevent any subscriptions from happening.
+
+```ruby
+require "signalize"
+include Signalize::API
+
+counter = signal(0)
+effect_count = signal(0)
+fn = proc { effect_count.value + 1 }
+
+effect do
+  # Logs the value
+	puts counter.value
+
+	# Whenever this effect is triggered, run `fn` that gives new value
+	effect_count.value = untracked(&fn)
+end
+```
+
 ### `computed { }`
 
 You derive computed state by accessing a signal's value within a `computed` block and returning a new value. Every time that signal value is updated, a computed value will likewise be updated. Actually, that's not quite accurate — the computed value only computes when it's read. In this sense, we can call computed values "lazily-evaluated".
@@ -211,7 +232,7 @@ end
 counter.value = 1 # logs the new value
 ```
 
-### `peek`
+### `signal.peek`
 
 If you need to access a signal's value inside an effect without subscribing to that signal's updates, use the `peek` method instead of `value`.
 
@@ -231,6 +252,55 @@ effect do
 end
 ```
 
+## Signalize Struct
+
+An optional add-on to Signalize, the `Singalize::Struct` class lets you define multiple signal or computed variables to hold in struct-like objects. You can even add custom methods to your classes with a simple DSL. (The API is intentionally similar to `Data` in Ruby 3.2+, although these objects are of course mutable.)
+
+Here's what it looks like:
+
+```ruby
+require "signalize/struct"
+
+include Signalize::API
+
+TestSignalsStruct = Signalize::Struct.define(
+  :str,
+  :int,
+  :multiplied_by_10
+) do # optional block for adding methods
+  def increment!
+    self.int += 1
+  end
+end
+
+struct = TestSignalsStruct.new(
+  int: 0,
+  str: "Hello World",
+  multiplied_by_10: computed { struct.int * 10 }
+)
+
+effect do
+  puts struct.multiplied_by_10 # 0
+end
+
+effect do
+  puts struct.str # "Hello World"
+end
+
+struct.increment! # above effect will now output 10
+struct.str = "Goodbye!" # above effect will now output "Goodbye!"
+```
+
+If you ever need to get at the actual `Signal` object underlying a value, just call `*_signal`. For example, you could call `int_signal` for the above example to get a signal object for `int`.
+
+Signalize structs require all of their members to be present when initializing…you can't pass only some keyword arguments.
+
+Signalize structs support `to_h` as well as `deconstruct_keys` which is used for pattern matching and syntax like `struct => { str: }` to set local variables.
+
+You can call `members` (as both object/class methods) to get a list of the value names in the struct.
+
+Finally, both `inspect` and `to_s` let you debug the contents of a struct.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rake test` to run the tests, or `bin/guard` or run them continuously in watch mode. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -239,7 +309,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Signalize is considered a direct port of the [original Signals JavaScript library](https://github.com/preactjs/signals). This means we are unlikely to accept any additional features other than what's provided by Signals. If Signals adds new functionality in the future, we will endeavor to replicate it in Signalize. Furthermore, if there's some unwanted behavior in Signalize that's also present in Signals, we are unlikely to modify that behavior.
+Signalize is considered a direct port of the [original Signals JavaScript library](https://github.com/preactjs/signals). This means we are unlikely to accept any additional features other than what's provided by Signals (unless it's completely separate, like our `Signalize::Struct` add-on). If Signals adds new functionality in the future, we will endeavor to replicate it in Signalize. Furthermore, if there's some unwanted behavior in Signalize that's also present in Signals, we are unlikely to modify that behavior.
 
 However, if you're able to supply a bugfix or performance optimization which will help bring Signalize _more_ into alignment with its Signals counterpart, we will gladly accept your PR!
 

data/lib/signalize/struct.rb

@@ -0,0 +1,91 @@
+require "signalize"
+
+module Signalize
+  class Struct
+    module Accessors
+      def members
+        @members ||= []
+      end
+
+      def signal_accessor(*names)
+        names.each do |name|
+          members.push(name.to_sym) unless members.find { _1 == name.to_sym }
+          signal_getter_name = "#{name}_signal".freeze
+          ivar_name = "@#{name}".freeze
+  
+          define_method "#{name}_signal" do
+            instance_variable_get(ivar_name)
+          end
+  
+          define_method name do
+            send(signal_getter_name)&.value
+          end
+  
+          define_method "#{name}=" do |val|
+            if instance_variable_defined?(ivar_name)
+              raise Signalize::Error, "Cannot assign a signal to a signal value" if val.is_a?(Signalize::Signal)
+  
+              sig = instance_variable_get(ivar_name)
+              if sig.is_a?(Signalize::Computed)
+                raise Signalize::Error, "Cannot set value of computed signal `#{ivar_name.delete_prefix("@")}'"
+              end
+  
+              sig.value = val
+            else
+              val = Signalize.signal(val) unless val.is_a?(Signalize::Computed)
+              instance_variable_set(ivar_name, val)
+            end
+          end
+        end
+      end
+    end
+  
+    extend Accessors
+  
+    def self.define(*names, &block)
+      Class.new(self).tap do |struct|
+        struct.signal_accessor(*names)
+        struct.class_eval(&block) if block
+      end
+    end
+
+    def initialize(**data)
+      # The below code is all to replicate native Ruby ergonomics
+      unknown_keys = data.keys - members
+      unless unknown_keys.empty?
+        plural_suffix = unknown_keys.length > 1 ? "s" : ""
+        raise ArgumentError, "unknown keyword#{plural_suffix}: #{unknown_keys.map { ":#{_1}" }.join(", ")}"
+      end
+
+      missing_keys = members - data.keys
+      unless missing_keys.empty?
+        plural_suffix = missing_keys.length > 1 ? "s" : ""
+        raise ArgumentError, "missing keyword#{plural_suffix}: #{missing_keys.map { ":#{_1}" }.join(", ")}"
+      end
+
+      # Initialize with keyword arguments
+      data.each do |k, v|
+        send("#{k}=", v)
+      end
+    end
+
+    def members = self.class.members
+
+    def deconstruct_keys(...) = to_h.deconstruct_keys(...)
+
+    def to_h = members.each_with_object({}) { _2[_1] = send("#{_1}_signal").peek }
+
+    def inspect
+      var_peeks = instance_variables.filter_map do |var_name|
+        var = instance_variable_get(var_name)
+        "#{var_name.to_s.delete_prefix("@")}=#{var.peek.inspect}" if var.is_a?(Signalize::Signal)
+      end.join(", ")
+  
+      "#<#{self.class}#{var_peeks.empty? ? nil : " #{var_peeks}"}>"
+    end
+
+    def to_s
+      inspect
+    end
+  end
+end

data/lib/signalize/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Signalize
-  VERSION = "1.1.0"
+  VERSION = "1.3.0"
 end

data/lib/signalize.rb

@@ -21,6 +21,10 @@ module Signalize
 	  raise Signalize::Error, "Cycle detected"
   end
 
+  def self.mutation_detected
+	  raise Signalize::Error, "Computed cannot have side-effects"
+  end
+
   RUNNING = 1 << 0
   NOTIFIED = 1 << 1
   OUTDATED = 1 << 2
@@ -34,6 +38,10 @@ module Signalize
   global_map_accessor :eval_context
   self.eval_context = nil
 
+  # Used by `untracked` method
+  global_map_accessor :untracked_depth
+  self.untracked_depth = 0
+
   # Effects collected into a batch.
   global_map_accessor :batched_effect
   self.batched_effect = nil
@@ -414,6 +422,8 @@ module Signalize
     end
 
     def value=(value)
+      Signalize.mutation_detected if Signalize.eval_context.is_a?(Signalize::Computed)
+
       if value != @value
         Signalize.cycle_detected if Signalize.batch_iteration > 100
 
@@ -484,7 +494,7 @@ module Signalize
         return true
       end
     
-      prevContext = Signalize.eval_context
+      prev_context = Signalize.eval_context
       begin
         Signalize.prepare_sources(self)
         Signalize.eval_context = self
@@ -499,7 +509,7 @@ module Signalize
         @_flags |= HAS_ERROR
         @_version += 1
       end
-      Signalize.eval_context = prevContext
+      Signalize.eval_context = prev_context
       Signalize.cleanup_sources(self)
       @_flags &= ~RUNNING
 
@@ -667,6 +677,21 @@ module Signalize
         Signalize.end_batch
       end
     end
+
+    def untracked
+      return yield unless Signalize.untracked_depth.zero?
+
+      prev_context = Signalize.eval_context
+      Signalize.eval_context = nil
+      Signalize.untracked_depth += 1
+
+      begin
+        return yield
+      ensure
+        Signalize.untracked_depth -= 1
+        Signalize.eval_context = prev_context
+      end
+    end
   end
 
   extend API

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: signalize
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Jared White
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-25 00:00:00.000000000 Z
+date: 2023-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -42,6 +42,7 @@ files:
 - README.md
 - Rakefile
 - lib/signalize.rb
+- lib/signalize/struct.rb
 - lib/signalize/version.rb
 - signalize.gemspec
 homepage: https://github.com/whitefusionhq/signalize