phlex-reactive 0.13.0 → 0.13.2

data/lib/phlex/reactive/streamable.rb

@@ -50,6 +50,10 @@ module Phlex
         prepend: "prepend", remove: "remove", js: "reactive:js"
       }.freeze
       BROADCAST_SELF_TARGETING = %i[replace remove].freeze
+      # The broadcast_collection_to verbs (issue #248) — a collection DELTA, so
+      # only the three that change the size. (A `replace:` row is an ordinary
+      # broadcast_to: it moves no boundary and needs no count refresh.)
+      COLLECTION_VERBS = %i[append prepend remove].freeze
       BROADCAST_CONTAINER = %i[update append prepend].freeze
       BROADCAST_MORPHABLE = %i[replace update].freeze
 
@@ -118,7 +122,8 @@ module Phlex
         # thread-local path (so exclude:/visible_to: reach pgbus and Action Cable
         # no-ops). Self-targeting verbs derive the target from the component's #id
         # and REQUIRE a Streamable payload; container verbs need an explicit target.
-        def broadcast_component(owner, verb, payload, component, keys, morph:, target:, exclude:, visible_to:, effect: nil)
+        def broadcast_component(owner, verb, payload, component, keys, morph:, target:, exclude:, visible_to:,
+                                effect: nil, coalesce: nil)
           if verb == :js && !effect.nil?
             raise ArgumentError,
               "broadcast_to js: takes no effect: — effects animate element streams (replace/update/" \
@@ -136,7 +141,7 @@ module Phlex
           Phlex::Reactive.instrument(
             "broadcast", { component: component_name, stream_action: BROADCAST_VERBS[verb], streamables: keys.size }
           ) do
-            with_pgbus_broadcast_opts(exclude:, visible_to:) do
+            with_pgbus_broadcast_opts(exclude:, visible_to:, coalesce:) do
               # A broadcast render NEVER inherits the actor's url_options (issue
               # #232): this call may run inside an action request (where the
               # endpoint threaded the actor's host), but subscribers can be on
@@ -150,6 +155,21 @@ module Phlex
           end
         end
 
+        # Broadcast ALREADY-RENDERED html (issue #248) — no component to build or
+        # render. The count companion is a plain number, not a component, so it
+        # has no render leg; everything else (instrumentation, the pgbus
+        # thread-locals, the per-key dispatch) is identical to
+        # broadcast_component.
+        def broadcast_raw(owner, verb, target, html, keys, exclude: nil, visible_to: nil, coalesce: nil)
+          Phlex::Reactive.instrument(
+            "broadcast", { component: owner.name, stream_action: BROADCAST_VERBS[verb], streamables: keys.size }
+          ) do
+            with_pgbus_broadcast_opts(exclude:, visible_to:, coalesce:) do
+              keys.each { dispatch_broadcast(verb, it, target, html, nil, false, nil) }
+            end
+          end
+        end
+
         # Validate + serialize broadcast ops: reject actor-only ops (focus steals
         # focus in every tab; submit force-submits every subscriber's form;
         # paste_into reads every subscriber's clipboard) and an empty chain (a
@@ -189,18 +209,27 @@ module Phlex
         # instrument_broadcast uses (issue #185/#187). Duplicated at module level so
         # the shared broadcast_component owns its transport threading. On Action
         # Cable / old pgbus this is a pure `yield`.
-        def with_pgbus_broadcast_opts(exclude:, visible_to:)
+        # `coalesce:` (issue #248) rides the SAME thread-local convention. Unlike
+        # a kwarg, an unknown thread-local is silently IGNORED by a pgbus that
+        # does not forward it (pre-zoolutions/pgbus#465) — so setting it is
+        # always safe: an old pgbus just does not coalesce (more messages, same
+        # correctness), a new one does. That is why there is no capability gate
+        # here beyond the existing pgbus_streams? one.
+        def with_pgbus_broadcast_opts(exclude:, visible_to:, coalesce: nil)
           return yield unless Phlex::Reactive.pgbus_streams?
 
           prev_exclude = Thread.current[:pgbus_broadcast_exclude]
           prev_visible = Thread.current[:pgbus_broadcast_visible_to]
+          prev_coalesce = Thread.current[:pgbus_broadcast_coalesce]
           Thread.current[:pgbus_broadcast_exclude] = exclude
           Thread.current[:pgbus_broadcast_visible_to] = visible_to
+          Thread.current[:pgbus_broadcast_coalesce] = coalesce
           yield
         ensure
           if Phlex::Reactive.pgbus_streams?
             Thread.current[:pgbus_broadcast_exclude] = prev_exclude
             Thread.current[:pgbus_broadcast_visible_to] = prev_visible
+            Thread.current[:pgbus_broadcast_coalesce] = prev_coalesce
           end
         end
 
@@ -494,6 +523,49 @@ module Phlex
           )
         end
 
+        # Broadcast a collection DELTA — the row PLUS the count companion PLUS
+        # the 0<->1 empty-state toggle (issue #248), the broadcast-side
+        # counterpart of reply.append / reply.remove.
+        #
+        #   Container.broadcast_collection_to(@list, :todos,
+        #     container: @list_component, append: todo, in: :todos,
+        #     exclude: reactive_connection_id)
+        #
+        # broadcast_to(append:) deliberately emits the BARE row: it has no
+        # container instance, so it cannot resolve the declaration or run the
+        # size resolver. This verb takes that instance as `container:` and runs
+        # the SAME Phlex::Reactive::Collections decisions the reply path runs,
+        # so a peer's list stays as correct as the actor's.
+        #
+        # `in:` names the declared reactive_collection; the verb is `append:`,
+        # `prepend:` or `remove:` (exactly one). `exclude:`/`visible_to:` thread
+        # to pgbus as everywhere else.
+        #
+        # `row:` is the row component's extra init kwargs (issue #186's row_kwargs
+        # on the reply side) — pass the SAME ones the actor got, or a peer whose
+        # row component has a required kwarg raises instead of rendering.
+        #
+        # `coalesce:` (a window in ms, or true) applies to the AGGREGATE streams
+        # only — the count companion and the empty-state toggle are idempotent
+        # replaces of stable targets, so a 177-row fan-out collapses to a
+        # handful of count refreshes. The ROW stream is NEVER coalesced: an
+        # append is not idempotent and each row is a distinct target. Needs
+        # pgbus with zoolutions/pgbus#465; on anything older the thread-local is
+        # ignored and every aggregate stream simply goes out (correct, chattier).
+        # (`in:` is a Ruby keyword, so it cannot be a named parameter — it is
+        # pulled out of **opts, which then holds exactly the verb kwarg.)
+        def broadcast_collection_to(*streamables, container:, exclude: nil, visible_to: nil,
+                                    coalesce: nil, effect: nil, row: {}, **opts)
+          name = opts.delete(:in) ||
+                 raise(ArgumentError, "broadcast_collection_to needs in: :collection_name")
+          action, model = extract_collection_verb(opts)
+          definition = Phlex::Reactive::Collections.definition!(container, name)
+          keys = [streamables]
+
+          broadcast_collection_row(definition, action, model, keys, exclude:, visible_to:, effect:, row:)
+          broadcast_collection_aggregates(definition, container, action, keys, exclude:, visible_to:, coalesce:)
+        end
+
         # Define the guided-error stub for each removed broadcast method (issue
         # #185). `verb` is referenced in define_method AND the message, so the outer
         # block param must be named — `it` is illegal here.
@@ -519,6 +591,77 @@ module Phlex
           verb.first
         end
 
+        # The collection verb split — append:/prepend:/remove:, exactly one.
+        def extract_collection_verb(verb)
+          unless verb.size == 1 && COLLECTION_VERBS.include?(verb.keys.first)
+            raise ArgumentError,
+              "broadcast_collection_to needs exactly ONE verb kwarg " \
+              "(#{COLLECTION_VERBS.join("/")}), got #{verb.keys.inspect}"
+          end
+
+          verb.first
+        end
+
+        # The ROW leg: routed through the ordinary broadcast_to so the row is
+        # built, rendered and instrumented exactly like every other broadcast.
+        # Never coalesced (distinct targets; an append is not idempotent).
+        #
+        # A STRING model is an already-built dom id, the same form
+        # reply.remove(id, from:) and Collections.row_remove_stream accept.
+        # Building a row component from it would hand the id to the component's
+        # initializer as if it were a record — so it short-circuits to a raw
+        # remove of that target instead.
+        def broadcast_collection_row(definition, action, model, keys, exclude:, visible_to:, effect:, row: {})
+          if action == :remove
+            if model.is_a?(::String)
+              return Phlex::Reactive::Streamable.broadcast_raw(
+                definition.item, :remove, model, nil, keys, exclude:, visible_to:
+              )
+            end
+
+            return Phlex::Reactive::Streamable.broadcast_component(
+              definition.item, :remove, model, definition.item.send(:build, model, row), keys,
+              morph: false, target: nil, exclude:, visible_to:, effect:
+            )
+          end
+
+          Phlex::Reactive::Streamable.broadcast_component(
+            definition.item, action, model, definition.item.send(:build, model, row), keys,
+            morph: false, target: definition.container, exclude:, visible_to:, effect:
+          )
+        end
+
+        # The AGGREGATE leg: the count companion and the empty-state toggle,
+        # both idempotent replaces of stable targets — so both carry `coalesce:`.
+        def broadcast_collection_aggregates(definition, container, action, keys, exclude:, visible_to:, coalesce:)
+          delta = action == :remove ? :remove : :add
+          # Resolve the size ONCE (it is usually a DB count) and hand the same
+          # value to both decisions — see Collections.size_of.
+          size = Phlex::Reactive::Collections.size_of(definition, container)
+
+          if (refresh = Phlex::Reactive::Collections.count_refresh(definition, container, size))
+            # NOT `target, size = refresh` — that would rebind `size` to the
+            # count's STRING form and hand a String to empty_toggle below.
+            count_target, count_html = refresh
+            Phlex::Reactive::Streamable.broadcast_raw(
+              self, :update, count_target, count_html, keys, exclude:, visible_to:, coalesce:
+            )
+          end
+
+          case Phlex::Reactive::Collections.empty_toggle(definition, container, delta, size)
+          when :clear
+            Phlex::Reactive::Streamable.broadcast_component(
+              definition.empty, :remove, nil, definition.empty.new, keys,
+              morph: false, target: nil, exclude:, visible_to:, coalesce:
+            )
+          when :restore
+            Phlex::Reactive::Streamable.broadcast_component(
+              definition.empty, :append, nil, definition.empty.new, keys,
+              morph: false, target: definition.container, exclude:, visible_to:, coalesce:
+            )
+          end
+        end
+
         # Coerce a verb payload into a built component: a Phlex component passes
         # through (issue #185 — built payloads); a Hash is init kwargs verbatim (no
         # **options collision); anything else is the record built via

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.13.0"
+    VERSION = "0.13.2"
   end
 end

data/lib/phlex/reactive.rb

@@ -712,6 +712,41 @@ module Phlex
         defined?(::ActiveJob::Base) ? true : false
       end
 
+      # --- Async-action lifecycle / settles (issue #248) -----------------
+
+      # NOTE: there is deliberately NO settle_token_ttl. Issue #248's sketch had
+      # one for a fallback PULL token, but a settle has no pull lane at all — the
+      # client cannot poll "is the job done yet", and redeeming such a token at
+      # the defer endpoint would render the PRE-JOB component, which is the exact
+      # bug reply.pending exists to fix. A setting that cannot change behavior is
+      # worse than no setting: it tells an operator they can extend a wait window
+      # that is not governed by a token in the first place. The settle's wait is
+      # bounded by the JOB, not by a TTL.
+
+      # Window (ms) the AGGREGATE settle streams coalesce on — the count
+      # companion, the empty-state toggle, any companion refresh. They are
+      # idempotent replaces of stable targets, so a 177-row fan-out collapses to
+      # a handful of them instead of 177. The ROW streams are never coalesced.
+      # Needs pgbus with zoolutions/pgbus#465 on the peers path; without it the
+      # window is simply ignored. nil resets to the default.
+      attr_writer :settle_coalesce_window_ms
+
+      def settle_coalesce_window_ms
+        @settle_coalesce_window_ms ||= 50
+      end
+
+      # Can reply.pending mint a settle handle at all? A settle has NO pull
+      # fallback — the client cannot poll "is the job done yet" — so it needs
+      # the defer PUSH lane (durable pgbus one-shot stream + ActiveJob). A
+      # forced defer_transport of :fetch is therefore also a no.
+      #
+      # False does NOT break anything: reply.pending degrades to a plain
+      # enqueue (no pending markers, no handle, reactive_settle no-ops in the
+      # job) — today's behavior, never a permanently pending row.
+      def settle_capable?
+        defer_push_capable? && defer_transport != :fetch
+      end
+
       # DOM id of the host-app container a Response#flash appends into.
       # Default "flash"; override to match your layout's flash region.
       def flash_target

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.13.2
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -153,6 +153,7 @@ files:
 - lib/phlex/reactive/authorization.rb
 - lib/phlex/reactive/claude/skills/phlex-reactive-debugging/SKILL.md
 - lib/phlex/reactive/client_bindings.rb
+- lib/phlex/reactive/collections.rb
 - lib/phlex/reactive/component.rb
 - lib/phlex/reactive/component/dsl.rb
 - lib/phlex/reactive/component/helpers.rb
@@ -178,8 +179,11 @@ files:
 - lib/phlex/reactive/mcp/tools/doctor_tool.rb
 - lib/phlex/reactive/mcp/tools/find_tool.rb
 - lib/phlex/reactive/param_schema.rb
+- lib/phlex/reactive/pending.rb
 - lib/phlex/reactive/reply.rb
 - lib/phlex/reactive/response.rb
+- lib/phlex/reactive/settle.rb
+- lib/phlex/reactive/settles.rb
 - lib/phlex/reactive/show_conditions.rb
 - lib/phlex/reactive/stream.rb
 - lib/phlex/reactive/streamable.rb