phlex-reactive 0.12.6 → 0.13.1

data/lib/phlex/reactive/response.rb

@@ -119,87 +119,64 @@ module Phlex
         # `effect:` (issue #215) stamps the ROW stream only — the count
         # companion and the empty-state toggle are bookkeeping, not the thing
         # entering/leaving.
+        # Issue #248: the bookkeeping BODIES moved to Phlex::Reactive::Collections
+        # so the job-side settle and the peers broadcast run the SAME code. These
+        # builders keep their exact behaviour by delegating.
         def build_collection_append(component, name, model, effect: nil, **row_kwargs)
-          definition = collection_def!(component, name)
-          new(streams: collection_add_streams(definition, component, model, :append, row_kwargs, effect:),
-            render_self: false, token_component: component)
+          definition = Phlex::Reactive::Collections.definition!(component, name)
+          new(streams: Phlex::Reactive::Collections.add_streams(definition, component, model, :append, row_kwargs,
+            effect:), render_self: false, token_component: component)
         end
 
         def build_collection_prepend(component, name, model, effect: nil, **row_kwargs)
-          definition = collection_def!(component, name)
-          new(streams: collection_add_streams(definition, component, model, :prepend, row_kwargs, effect:),
-            render_self: false, token_component: component)
+          definition = Phlex::Reactive::Collections.definition!(component, name)
+          new(streams: Phlex::Reactive::Collections.add_streams(definition, component, model, :prepend, row_kwargs,
+            effect:), render_self: false, token_component: component)
         end
 
         def build_collection_remove(component, name, model, effect: nil)
-          definition = collection_def!(component, name)
-          new(streams: collection_remove_streams(definition, component, model, effect:),
+          definition = Phlex::Reactive::Collections.definition!(component, name)
+          new(streams: Phlex::Reactive::Collections.remove_streams(definition, component, model, effect:),
             render_self: false, token_component: component)
         end
 
-        private
-
-        # Resolve the declaration off the container's class, raising a clear error
-        # for an undeclared name (a typo'd collection should fail loudly, not
-        # silently emit an empty Response).
-        def collection_def!(component, name)
-          component.class.reactive_collections[name.to_sym] ||
-            raise(Phlex::Reactive::Error, "undeclared reactive_collection :#{name} on #{component.class}")
-        end
-
-        # Row add (append/prepend) + count + empty-state clear. The empty-state is
-        # removed only when the list just crossed 0->1 (size == 1) — appending to
-        # an already-populated list leaves it untouched.
-        def collection_add_streams(definition, component, model, action, row_kwargs = {}, effect: nil)
-          # row_kwargs (issue #186) thread to the row component's init via the class
-          # stream builder's **options passthrough (ItemRow.new(model:, **row_kwargs)).
-          streams = [definition.item.public_send(action, target: definition.container, model:, effect:, **row_kwargs)]
-          append_count_stream(streams, definition, component)
-
-          size = definition.size_for(component)
-          streams << definition.empty.new.to_stream_remove if definition.empty && size == 1
-          streams
-        end
-
-        # Row remove + count + empty-state restore. The empty-state is appended
-        # back into the container only when the list just emptied (size == 0).
-        def collection_remove_streams(definition, component, model, effect: nil)
-          streams = [collection_row_remove(definition, model, effect)]
-          append_count_stream(streams, definition, component)
-
-          size = definition.size_for(component)
-          if definition.empty && size&.zero?
-            # Render the empty-state and append it INTO the container (not its
-            # own id) — restoring "No items yet" when the last row was removed.
-            # model: nil builds it argument-free (an empty-state is a static view).
-            streams << definition.empty.append(target: definition.container, model: nil)
+        # --- Async-action lifecycle (issue #248) ---
+        # Mark targets pending and hand the fulfilment to the app's own job. The
+        # reply deliberately does NOT re-render the container: re-rendering it
+        # here would draw the PRE-JOB world (the endpoint renders inside the
+        # transaction; the queue publishes on commit) — the exact bug this verb
+        # exists to fix. render_self is therefore false, with the container as
+        # token_component so the signed token still rolls forward (cosmos#1939 —
+        # without it the list is act-once-only).
+        #
+        # The Response only RECORDS the segment; the ENDPOINT turns it into the
+        # marker + directive streams after the transaction committed.
+        # Pull `in:` out of reply.pending's **opts and REFUSE anything left over.
+        # `in` is a Ruby keyword, so it cannot be a named parameter — which means
+        # every other keyword lands in **opts and would otherwise be silently
+        # dropped. A typo (`jbo:` for `job:`) would then mark the rows pending
+        # and enqueue NOTHING: a permanently shimmering row, the exact failure
+        # this feature exists to prevent. So it fails at the call site instead.
+        def pending_collection!(opts)
+          collection = opts.delete(:in)
+          unless opts.empty?
+            raise ArgumentError,
+              "reply.pending got unknown keyword(s) #{opts.keys.map(&:inspect).join(", ")} — " \
+              "it takes in:, job:, args:, peers: and a block. A dropped keyword would mark the " \
+              "targets pending with nothing to settle them."
           end
-          streams
-        end
 
-        # Remove the row by its DOM id. Accepts the record (so dom_id is derived)
-        # or an already-built dom-id string (e.g. the value the row used as #id).
-        def collection_row_remove(definition, model, effect = nil)
-          if model.is_a?(String)
-            Phlex::Reactive::Effects.annotate(Phlex::Reactive.stream_builder.remove(model), effect)
-          else
-            definition.item.remove(model, effect:)
-          end
+          collection
         end
 
-        # Append the count companion's update stream when a count id + a size
-        # resolver are both declared. The size is a number, HTML-escaped by Turbo.
-        def append_count_stream(streams, definition, component)
-          return unless definition.count
-
-          size = definition.size_for(component)
-          return if size.nil?
-
-          streams << update_stream(definition.count, size.to_s)
+        def build_pending(component, records, collection:, peers:, job:, args:, enqueue:)
+          segment = Phlex::Reactive::Pending.build_segment(
+            component, records, collection:, peers:, job:, args:, enqueue:
+          )
+          new(streams: [], render_self: false, token_component: component,
+            pending_segments: segment ? [segment] : NO_SEGMENTS)
         end
 
-        public
-
         # Partial / per-field update with a TOKEN-ONLY refresh (issue #30). Emits
         # EXACTLY the given streams — no forced full-self replace — but binds
         # `component` so the endpoint appends its tiny `to_stream_token` stream.
@@ -376,13 +353,14 @@ data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
       NO_SEGMENTS = [].freeze
 
       def initialize(streams: [], redirect_url: nil, render_self: true, token_component: nil,
-                     subject_component: nil, deferred_segments: NO_SEGMENTS)
+                     subject_component: nil, deferred_segments: NO_SEGMENTS, pending_segments: NO_SEGMENTS)
         @streams = streams.freeze
         @redirect_url = redirect_url
         @render_self = render_self
         @token_component = token_component
         @subject_component = subject_component
         @deferred_segments = deferred_segments.freeze
+        @pending_segments = pending_segments.freeze
         freeze
       end
 
@@ -394,6 +372,13 @@ data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
 
       def deferred? = !@deferred_segments.empty?
 
+      # The recorded reply.pending segments (issue #248), in call order. Same
+      # contract as deferred_segments: recorded here, turned into wire streams
+      # by the endpoint AFTER the transaction committed.
+      attr_reader :pending_segments
+
+      def pending? = !@pending_segments.empty?
+
       # Append extra turbo-stream strings (a sibling component, a flash).
       # Returns a NEW Response (immutable).
       def stream(*more)
@@ -403,7 +388,8 @@ data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
           render_self: @render_self,
           token_component: @token_component,
           subject_component: @subject_component,
-          deferred_segments: @deferred_segments
+          deferred_segments: @deferred_segments,
+          pending_segments: @pending_segments
         )
       end
 
@@ -434,7 +420,52 @@ data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
           token_component: @token_component,
           subject_component: @subject_component,
           deferred_segments: @deferred_segments +
-            [Phlex::Reactive::Defer::Segment.new(component:, placeholder:, morph:)]
+            [Phlex::Reactive::Defer::Segment.new(component:, placeholder:, morph:)],
+          pending_segments: @pending_segments
+        )
+      end
+
+      # Chain reply.pending onto an existing reply (issue #248), so an action can
+      # do one synchronous thing AND mark other targets pending:
+      #
+      #   reply.replace.pending(rows, in: :declined, job: RestoreJob)
+      #
+      # Dead on a redirect, exactly like #defer: the client is navigating away,
+      # so the settle could never land.
+      def pending(records, peers: false, job: nil, args: nil, **opts, &enqueue)
+        if redirect?
+          raise Phlex::Reactive::Error,
+            "reply.pending on a redirect reply is dead — the client is navigating away, " \
+            "so the settle could never land"
+        end
+
+        subject = pending_subject!
+        # ONE subscription per anchor. Every pending segment on the same
+        # container emits a directive targeting that container's id, and the
+        # client keys its in-flight subscriptions BY TARGET — so a second
+        # directive supersedes the first, silently orphaning the jobs the first
+        # call enqueued. Two pending calls on one container in one reply is a
+        # call-site mistake; make it a loud one.
+        if @pending_segments.any? { it.handle.anchor == subject.id }
+          raise Phlex::Reactive::Error,
+            "reply.pending was called twice for #{subject.class} (##{subject.id}) — the second " \
+            "subscription would supersede the first on the client, so the first call's jobs could " \
+            "never settle. Mark every target in ONE reply.pending call (the settle names its own " \
+            "collection: s.remove(record, from: :name))."
+        end
+
+        built = self.class.build_pending(
+          subject, records, collection: self.class.pending_collection!(opts),
+          peers:, job:, args:, enqueue:
+        )
+        self.class.new(
+          streams: @streams,
+          redirect_url: @redirect_url,
+          render_self: @render_self,
+          token_component: @token_component || built.token_component,
+          subject_component: @subject_component,
+          deferred_segments: @deferred_segments,
+          pending_segments: @pending_segments + built.pending_segments
         )
       end
 
@@ -537,6 +568,16 @@ data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
 
       private
 
+      # The container a chained .pending marks: the component this reply is
+      # already bound to. A subject-free reply (reply.with) has none — chaining
+      # .pending onto it is a call-site mistake, so it fails loudly.
+      def pending_subject!
+        (@subject_component || @token_component) ||
+          raise(Phlex::Reactive::Error,
+            "reply.pending needs a bound component (the container that owns the collection) — " \
+            "chain it off a component verb (reply.replace.pending(...)) or call reply.pending(...) directly")
+      end
+
       # The default `target` for #js: the bound component's id when this reply is
       # component-scoped (replace/morph/update set subject_component; .streams and
       # collections set token_component), else nil — a subject-free reply.with is

data/lib/phlex/reactive/settle.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # The job-side reply builder (issue #248) — what `reactive_settle` yields.
+    #
+    #   reactive_settle do |s|
+    #     if result.success?
+    #       s.remove(transfer, from: :unreconcilable)
+    #     else
+    #       s.replace(transfer)
+    #       s.flash(:alert, result.error)
+    #     end
+    #   end
+    #
+    # The verbs mirror `reply.*` and, critically, route through the SAME
+    # Phlex::Reactive::Collections decisions — so a job-side append emits the
+    # row AND the count companion AND the 0<->1 empty-state toggle, instead of
+    # the bare row `broadcast_to(append:)` gives you. That shared bookkeeping is
+    # the whole point: it is what the app can no longer get subtly wrong.
+    #
+    # Unlike Response, Settle is a MUTABLE accumulator, not a value object: a
+    # settle block is imperative (branch on the work's result, add a flash) and
+    # every verb returns self so the calls can also be chained.
+    #
+    # It collects streams; Phlex::Reactive::Settles owns the delivery — one
+    # durable message to the actor's shared one-shot stream, plus the optional
+    # peers broadcast.
+    class Settle
+      attr_reader :streams
+
+      # The rebuilt container — Settles reads it for the peers broadcast (it
+      # carries the collection declaration and the size resolver).
+      attr_reader :container
+
+      # `container` is the rebuilt container component (from_identity, off the
+      # request thread); `handle` is the Pending::Handle the enqueue captured.
+      def initialize(container, handle)
+        @container = container
+        @handle = handle
+        @streams = []
+        @peer_ops = []
+      end
+
+      # Re-render ONE row in place. The work ran and the row is simply different
+      # now (a failed re-execution going back to actionable, say). No count or
+      # empty-state stream: a replace cannot change the size.
+      #
+      # Accepts a record (resolved through the collection's row component) or a
+      # built Streamable component (its own #id is the target).
+      def replace(model, morph: false, effect: nil, **row_kwargs)
+        if model.is_a?(Phlex::Reactive::Streamable)
+          @streams << model.to_stream_replace(morph:, effect:)
+          # A built component carries its own identity, so peers can be handed
+          # the same instance — no definition needed.
+          @peer_ops << [nil, :replace, model, {}] if @handle.peers
+          return self
+        end
+
+        definition = definition!(nil)
+        @streams.concat(Phlex::Reactive::Collections.replace_streams(definition, model, effect:, **row_kwargs))
+        # A replace is NOT a collection delta (it moves no boundary), but peers
+        # still need it: without this, a failed re-execution goes back to
+        # actionable for the actor while every other operator keeps the stale
+        # row. It rides the ordinary row broadcast, not broadcast_collection_to.
+        peer(definition, :replace, model, row_kwargs)
+        self
+      end
+
+      # Remove a row: the row + the count companion + the empty-state restore at
+      # the 1->0 boundary. `from:` defaults to the collection reply.pending
+      # named, so the common case reads `s.remove(transfer)`.
+      def remove(model, from: nil, effect: nil)
+        definition = definition!(from)
+        @streams.concat(Phlex::Reactive::Collections.remove_streams(definition, @container, model, effect:))
+        peer(definition, :remove, model, {})
+        self
+      end
+
+      # Add a row: the row + the count companion + the empty-state clear at the
+      # 0->1 boundary.
+      def append(model, to: nil, effect: nil, **row_kwargs)
+        add(:append, model, to, effect, row_kwargs)
+      end
+
+      def prepend(model, to: nil, effect: nil, **row_kwargs)
+        add(:prepend, model, to, effect, row_kwargs)
+      end
+
+      # The case that motivated the whole issue: the work moved a record between
+      # two lists. Ordered remove-then-append so the size resolvers run against
+      # the post-move world in the order a reader expects, and so a row can
+      # never be momentarily present in both containers.
+      def move(model, from:, to:, effect: nil, **row_kwargs)
+        remove(model, from:, effect:)
+        append(model, to:, effect:, **row_kwargs)
+      end
+
+      # Refresh ONLY the collection's count companion — for a settle that
+      # changed the size without adding or removing a visible row. `name`
+      # defaults to the collection reply.pending named.
+      def count(name = nil)
+        @streams.concat(Phlex::Reactive::Collections.count_streams(definition!(name), @container))
+        self
+      end
+
+      # Tell the operator what happened. The job is where the OUTCOME is known,
+      # so this is how the page stops saying "Queued" forever.
+      def flash(level, content, target: Phlex::Reactive.flash_target, dismiss_after: nil)
+        @streams << Phlex::Reactive::Response.send(:flash_stream, level, content, target:, dismiss_after:)
+        self
+      end
+
+      # Server-pushed client DOM ops, same vocabulary as reply.js. Defaults to
+      # the container's id so self-scoped ops just work.
+      def js(ops, target: :__default)
+        resolved = target == :__default ? @handle.anchor : target
+        @streams << Phlex::Reactive::Response.js_stream(ops, target: resolved)
+        self
+      end
+
+      # Escape hatch: raw <turbo-stream> strings, exactly like reply.streams.
+      def streams!(*more)
+        @streams.concat(more.flatten)
+        self
+      end
+
+      # The peer deltas recorded alongside the actor's streams (issue #248).
+      # Collected rather than broadcast inline so Settles can send them AFTER
+      # the actor's message — the actor paid for the click and should not wait
+      # behind a fan-out of channel calls.
+      attr_reader :peer_ops
+
+      private
+
+      def add(action, model, name, effect, row_kwargs)
+        definition = definition!(name)
+        @streams.concat(
+          Phlex::Reactive::Collections.add_streams(definition, @container, model, action, row_kwargs, effect:)
+        )
+        peer(definition, action, model, row_kwargs)
+        self
+      end
+
+      # Resolve the collection: the explicit keyword, else the one reply.pending
+      # named. A settle with neither is a call-site mistake — fail loudly rather
+      # than silently emit nothing.
+      def definition!(name)
+        resolved = name || @handle.collection
+        unless resolved
+          raise Phlex::Reactive::Error,
+            "this settle has no collection to work on — name it (s.remove(record, from: :items)) " \
+            "or pass in: to reply.pending so the settle inherits it"
+        end
+
+        Phlex::Reactive::Collections.definition!(@container, resolved)
+      end
+
+      # Record a peer delta (only when reply.pending asked for peers:). The row
+      # kwargs ride along: a peer whose row component has a required init kwarg
+      # would otherwise raise, and one with an optional kwarg would render
+      # different markup than the actor got.
+      def peer(definition, action, model, row_kwargs)
+        return unless @handle.peers
+
+        @peer_ops << [definition.name, action, model, row_kwargs]
+      end
+    end
+  end
+end