README.md in signalize-1.2.0 vs README.md in signalize-1.3.0

- old
+ new

@@ -23,11 +23,11 @@ $ gem install signalize ## 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)` The first building block is the `Signalize::Signal` class. You can think of this as a reactive value object which wraps an underlying primitive like String, Integer, Array, etc. @@ -230,11 +230,11 @@ 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`. ```ruby require "signalize" @@ -250,18 +250,67 @@ # But we don't want this signal to react to `effect_count` effect_count.value = effect_count.peek + 1 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. To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org). ## 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! This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/whitefusionhq/signalize/blob/main/CODE_OF_CONDUCT.md).