Skip to content

State observation via returning callbacks#3

Draft
Hexcede wants to merge 7 commits into
4812571:mainfrom
Hexcede:observe-states-strict
Draft

State observation via returning callbacks#3
Hexcede wants to merge 7 commits into
4812571:mainfrom
Hexcede:observe-states-strict

Conversation

@Hexcede

@Hexcede Hexcede commented Apr 25, 2025

Copy link
Copy Markdown
Contributor

Based on #2

This pull request aims to provide big usability improvements to the observe library by introducing new callback based APIs for representing raw data.

The new APIs reduce the amount of boilerplate required to write observers for things like Fusion states, which in the current version of observe requires extra intermediate Signal objects to be instantiated.

  • Implements new observer code by using callbacks returned from observe instead of signals passed to observe.
  • Re-implements the existing signal based code to use the callback-based APIs, by binding returned callbacks to the signals.
  • Adds the following State observers:
    • Adds Value, which returns a cleanup & onChanged function. The onChanged function, when called, will update the state of the observer.
    • Adds ClearableValue, which is almost identical to Value, except a value of nil is treated as a clear and does not invoke the handler (but does invoke cleanup).
      • This is shorthand for an observer with a guard clause on nil values, which is a common pattern. It is used by the existing Child and SetClearSignals observers.
      • It might be desirable to rename this to Clearable.
    • Adds Array for unordered arrays, which returns a cleanup, onAdded, and onRemoved.
      • Removals of duplicate values follow the ordering of a stack. I expect that, where order matters, this is typically the most sensible behaviour.
    • Adds Set for sets, returns a cleanup, onAdded, and onRemoved callback.
      • Note: onAdded will currently NOT invoke cleanup & re-invoke the handler on re-insertion of a value already present in the set. I am currently unsure if this is good in practice. The alternative would be more in-line with what existing observer APIs do even if it's a bit wasteful.
    • Adds DistinctArray for arrays with distinct (unique, non-duplicate) items. Identical to Set, other than its initial value being an array instead of a set.
      • It is valid to pass an array that contains duplicate values to begin with, the observer naturally conforms to appropriate expectations here.
      • Note: Like with Set, no re-invocation on re-insertion.
      • Additional note: DistinctArray currently has duplicated code used in Set. It might be desirable to remove DistinctArray and expect users to use Set themselves, or to alternatively implement DistinctArray using Set under the hood, simply passing in a blank array and adding the values using the callbacks. Should resolve this after Strict typing #2 is either merged or rejected.
    • Adds Map for maps, which returns a cleanup & onChanged function. The onChanged function takes a key and value argument. The handler also takes both a key and a value. Otherwise, works exactly how you would expect.

@Hexcede Hexcede force-pushed the observe-states-strict branch 2 times, most recently from 67eb265 to af2029d Compare April 25, 2025 17:06
@Hexcede Hexcede force-pushed the observe-states-strict branch from af2029d to 45c317b Compare April 25, 2025 17:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant