turbo-rails 0.5.0

data/app/channels/turbo/streams/broadcasts.rb

@@ -0,0 +1,66 @@
+# Provides the broadcast actions in synchronous and asynchrous form for the <tt>Turbo::StreamsChannel</tt>.
+# See <tt>Turbo::Broadcastable</tt> for the user-facing API that invokes these methods with most of the paperwork filled out already.
+#
+# Can be used directly using something like <tt>Turbo::StreamsChannel.broadcast_remove_to :entries, target: 1</tt>.
+module Turbo::Streams::Broadcasts
+  include Turbo::Streams::ActionHelper
+
+  def broadcast_remove_to(*streamables, target:)
+    broadcast_action_to *streamables, action: :remove, target: target
+  end
+
+  def broadcast_replace_to(*streamables, target:, **rendering)
+    broadcast_action_to *streamables, action: :replace, target: target, **rendering
+  end
+
+  def broadcast_append_to(*streamables, target:, **rendering)
+    broadcast_action_to *streamables, action: :append, target: target, **rendering
+  end
+
+  def broadcast_prepend_to(*streamables, target:, **rendering)
+    broadcast_action_to *streamables, action: :prepend, target: target, **rendering
+  end
+
+  def broadcast_action_to(*streamables, action:, target:, **rendering)
+    broadcast_stream_to *streamables, content: turbo_stream_action_tag(action, target: target, template:
+      rendering.delete(:content) || (rendering.any? ? render_format(:html, **rendering) : nil)
+    )
+  end
+
+
+  def broadcast_replace_later_to(*streamables, target:, **rendering)
+    broadcast_action_later_to *streamables, action: :replace, target: target, **rendering
+  end
+
+  def broadcast_append_later_to(*streamables, target:, **rendering)
+    broadcast_action_later_to *streamables, action: :append, target: target, **rendering
+  end
+
+  def broadcast_prepend_later_to(*streamables, target:, **rendering)
+    broadcast_action_later_to *streamables, action: :prepend, target: target, **rendering
+  end
+
+  def broadcast_action_later_to(*streamables, action:, target:, **rendering)
+    Turbo::Streams::ActionBroadcastJob.perform_later \
+      stream_name_from(streamables), action: action, target: target, **rendering
+  end
+
+
+  def broadcast_render_to(*streamables, **rendering)
+    broadcast_stream_to *streamables, content: render_format(:turbo_stream, **rendering)
+  end
+
+  def broadcast_render_later_to(*streamables, **rendering)
+    Turbo::Streams::BroadcastJob.perform_later stream_name_from(streamables), **rendering
+  end
+
+  def broadcast_stream_to(*streamables, content:)
+    ActionCable.server.broadcast stream_name_from(streamables), content
+  end
+
+
+  private
+    def render_format(format, **rendering)
+      ApplicationController.render(formats: [ format ], **rendering)
+    end
+end

data/app/channels/turbo/streams/stream_name.rb

@@ -0,0 +1,24 @@
+# Stream names are how we identify which updates should go to which users. All streams run over the same
+# <tt>Turbo::StreamsChannel</tt>, but each with their own subscription. Since stream names are exposed directly to the user
+# via the HTML stream subscription tags, we need to ensure that the name isn't tampered with, so the names are signed
+# upon generation and verified upon receipt. All verification happens through the <tt>Turbo.signed_stream_verifier</tt>.
+module Turbo::Streams::StreamName
+  # Used by <tt>Turbo::StreamsChannel</tt> to verify a signed stream name.
+  def verified_stream_name(signed_stream_name)
+    Turbo.signed_stream_verifier.verified signed_stream_name
+  end
+
+  # Used by <tt>Turbo::StreamsHelper#turbo_stream_from(*streamables)</tt> to generate a signed stream name.
+  def signed_stream_name(streamables)
+    Turbo.signed_stream_verifier.generate stream_name_from(streamables)
+  end
+
+  private
+    def stream_name_from(streamables)
+      if streamables.is_a?(Array)
+        streamables.map  { |streamable| stream_name_from(streamable) }.join(":")
+      else
+        streamables.then { |streamable| streamable.try(:to_gid_param) || streamable.to_param }
+      end
+    end
+end

data/app/channels/turbo/streams_channel.rb

@@ -0,0 +1,17 @@
+# The streams channel delivers all the turbo-stream actions created (primarily) through <tt>Turbo::Broadcastable</tt>.
+# A subscription to this channel is made for each individual stream that one wishes to listen for updates to.
+# The subscription relies on being passed a <tt>signed_stream_name</tt> parameter generated by turning a set of streamables
+# into signed stream name using <tt>Turbo::Streams::StreamName#signed_stream_name</tt>. This is automatically done
+# using the view helper <tt>Turbo::StreamsHelper#turbo_stream_from(*streamables)</tt>.
+# If the signed stream name cannot be verified, the subscription is rejected.
+class Turbo::StreamsChannel < ActionCable::Channel::Base
+  extend Turbo::Streams::Broadcasts, Turbo::Streams::StreamName
+
+  def subscribed
+    if verified_stream_name = self.class.verified_stream_name(params[:signed_stream_name])
+      stream_from verified_stream_name
+    else
+      reject
+    end
+  end
+end

data/app/controllers/turbo/frames/frame_request.rb

@@ -0,0 +1,24 @@
+# Turbo frame requests are requests made from within a turbo frame with the intention of replacing the content of just
+# that frame, not the whole page. They are automatically tagged as such by the Turbo Frame JavaScript, which adds a
+# <tt>Turbo-Frame</tt> header to the request. When that header is detected by the controller, we ensure that any
+# template layout is skipped (since we're only working on an in-page frame, thus can skip the weight of the layout), and
+# that the etag for the page is changed (such that a cache for a layout-less request isn't served on a normal request
+# and vice versa).
+#
+# This is merely a rendering optimization. Everything would still work just fine if we rendered everything including the layout.
+# Turbo Frames knows how to fish out the relevant frame regardless.
+#
+# This module is automatically included in <tt>ActionController::Base</tt>.
+module Turbo::Frames::FrameRequest
+  extend ActiveSupport::Concern
+
+  included do
+    layout -> { false if turbo_frame_request? }
+    etag { :frame if turbo_frame_request? }
+  end
+
+  private
+    def turbo_frame_request?
+      request.headers["Turbo-Frame"].present?
+    end
+end

data/app/controllers/turbo/native/navigation.rb

@@ -0,0 +1,49 @@
+# Turbo is built to work with native navigation principles and present those alongside what's required for the web. When you
+# have Turbo Native clients running (see the Turbo iOS and Turbo Android projects for details), you can respond to native
+# requests with three dedicated responses: <tt>recede</tt>, <tt>resume</tt>, <tt>refresh</tt>.
+#
+# FIXME: Supply full description of when we use either.
+module Turbo::Native::Navigation
+  private
+
+  def recede_or_redirect_to(url, **options)
+    turbo_native_action_or_redirect url, :recede, :to, options
+  end
+
+  def resume_or_redirect_to(url, **options)
+    turbo_native_action_or_redirect url, :resume, :to, options
+  end
+
+  def refresh_or_redirect_to(url, **options)
+    turbo_native_action_or_redirect url, :refresh, :to, options
+  end
+
+
+  def recede_or_redirect_back_or_to(url, **options)
+    turbo_native_action_or_redirect url, :recede, :back, options
+  end
+
+  def resume_or_redirect_back_or_to(url, **options)
+    turbo_native_action_or_redirect url, :resume, :back, options
+  end
+
+  def refresh_or_redirect_back_or_to(url, **options)
+    turbo_native_action_or_redirect url, :refresh, :back, options
+  end
+
+  # :nodoc:
+  def turbo_native_action_or_redirect(url, action, redirect_type, options = {})
+    if turbo_native_app?
+      redirect_to send("turbo_#{action}_historical_location_url", notice: options[:notice] || options.delete(:native_notice))
+    elsif redirect_type == :back
+      redirect_back fallback_location: url, **options
+    else
+      redirect_to url, options
+    end
+  end
+
+  # Turbo Native applications are identified by having the string "Turbo Native" as part of their user agent.
+  def turbo_native_app?
+    request.user_agent.to_s.match?(/Turbo Native/)
+  end
+end

data/app/controllers/turbo/native/navigation_controller.rb

@@ -0,0 +1,13 @@
+class Turbo::Native::NavigationController < ActionController::Base
+  def recede
+    render html: "Going back…"
+  end
+
+  def refresh
+    render html: "Refreshing…"
+  end
+
+  def resume
+    render html: "Staying put…"
+  end
+end

data/app/controllers/turbo/streams/turbo_streams_tag_builder.rb

@@ -0,0 +1,22 @@
+# Most turbo streams are rendered either asynchronously via <tt>Turbo::Broadcastable</tt>/<tt>Turbo::StreamsChannel</tt> or
+# rendered in templates with the <tt>turbo_stream.erb</tt> extension. But it's also possible to render updates inline
+# in controllers, like so:
+#
+#   def destroy
+#     @user.destroy!
+#
+#     respond_to do |format|
+#       format.turbo_stream { render turbo_stream: turbo_stream.remove(@user) }
+#       format.html         { redirect_to users_url, notice: "User removed" }
+#     end
+#   end
+#
+# This module adds that turbo_stream tag-builder object to all controllers. It's an instance of <tt>Turbo::Streams::TagBuilder</tt>
+# instantiated with the current <tt>view_context</tt>.
+module Turbo::Streams::TurboStreamsTagBuilder
+  private
+
+  def turbo_stream
+    Turbo::Streams::TagBuilder.new(view_context)
+  end
+end

data/app/helpers/turbo/drive_helper.rb

@@ -0,0 +1,16 @@
+module Turbo::DriveHelper
+  # Pages that are more likely than not to be a cache miss can skip turbo cache to avoid visual jitter.
+  # Note: This requires a +yield :head+ provision in the application layout.
+  #
+  # ==== Example
+  #
+  #   # app/views/application.html.erb
+  #   <html><head><%= yield :head %></head><body><%= yield %></html>
+  #
+  #   # app/views/trays/index.html.erb
+  #   <% turbo_exempts_page_from_cache %>
+  #   <p>Page that shouldn't be cached by Turbo</p>
+  def turbo_exempts_page_from_cache
+    provide :head, %(<meta name="turbo-cache-control" content="no-cache">).html_safe
+  end
+end

data/app/helpers/turbo/frames_helper.rb

@@ -0,0 +1,23 @@
+module Turbo::FramesHelper
+  # Returns a frame tag that can either be used simply to encapsulate frame content or as a lazy-loading container that starts empty but
+  # fetches the URL supplied in the +src+ attribute.
+  #
+  # === Examples
+  #
+  #   # => turbo-frame id="tray" src="http://example.com/trays/1"></turbo-frame>
+  #   <%= turbo_frame_tag "tray", src: tray_path(tray) %>
+  #
+  #   # => turbo-frame id="tray" links-target="top" src="http://example.com/trays/1"></turbo-frame>
+  #   <%= turbo_frame_tag "tray", src: tray_path(tray), links_target: "top" %>
+  #
+  #   # => turbo-frame id="tray" links-target="other_tray"></turbo-frame>
+  #   <%= turbo_frame_tag "tray", links_target: "other_tray" %>
+  #
+  #   # => turbo-frame id="tray"><div>My tray frame!</div></turbo-frame>
+  #   <%= turbo_frame_tag "tray" do %>
+  #     <div>My tray frame!</div>
+  #   <% end %>
+  def turbo_frame_tag(id, src: nil, target: nil, **attributes, &block)
+    tag.turbo_frame(**attributes.merge(id: id, src: src, target: target).compact, &block)
+  end
+end

data/app/helpers/turbo/includes_helper.rb

@@ -0,0 +1,5 @@
+module Turbo::IncludesHelper
+  def turbo_include_tags
+    javascript_include_tag("turbo", type: "module")
+  end
+end

data/app/helpers/turbo/streams/action_helper.rb

@@ -0,0 +1,25 @@
+module Turbo::Streams::ActionHelper
+  # Creates a `turbo-stream` tag according to the passed parameters. Examples:
+  #
+  #   # => <turbo-stream action="remove" target="message_1"></turbo-stream>
+  #   turbo_stream_action_tag "remove", target: "message_1"
+  #
+  #   # => <turbo-stream action="replace" target="message_1"><template><div id="message_1">Hello!</div></template></turbo-stream>
+  #   turbo_stream_action_tag "replace", target: "message_1", template: %(<div id="message_1">Hello!</div>)
+  def turbo_stream_action_tag(action, target:, template: nil)
+    target   = convert_to_turbo_stream_dom_id(target)
+    template = template ? "<template>#{template}</template>" : ""
+
+    %(<turbo-stream action="#{action}" target="#{target}">#{template}</turbo-stream>).html_safe
+  end
+
+  private
+    def convert_to_turbo_stream_dom_id(element_or_dom_id)
+      if element_or_dom_id.respond_to?(:to_key)
+        element = element_or_dom_id
+        ActionView::RecordIdentifier.dom_id(element)
+      else
+        dom_id = element_or_dom_id
+      end
+    end
+end

data/app/helpers/turbo/streams_helper.rb

@@ -0,0 +1,22 @@
+module Turbo::StreamsHelper
+  # Returns a new <tt>Turbo::Streams::TagBuilder</tt> object that accepts stream actions and renders them them as
+  # the template tags needed to send across the wire. This object is automatically yielded to turbo_stream.erb templates.
+  def turbo_stream
+    Turbo::Streams::TagBuilder.new(self)
+  end
+
+  # Used in the view to create a subscription to a stream identified by the <tt>streamables</tt> running over the
+  # <tt>Turbo::StreamsChannel</tt>. The stream name being generated is safe to embed in the HTML sent to a user without
+  # fear of tampering, as it is signed using <tt>Turbo.signed_stream_verifier</tt>. Example:
+  #
+  #   # app/views/entries/index.html.erb
+  #   <%= turbo_stream_from Current.account, :entries %>
+  #   <div id="entries">New entries will be appended to this container</div>
+  #
+  # The example above will process all turbo streams sent to a stream name like <tt>account:5:entries</tt>
+  # (when Current.account.id = 5). Updates to this stream can be sent like
+  # <tt>entry.broadcast_append_to entry.account, :entries, contrainer: "entries"</tt>.
+  def turbo_stream_from(*streamables)
+    tag.turbo_cable_stream_source channel: "Turbo::StreamsChannel", "signed-stream-name": Turbo::StreamsChannel.signed_stream_name(streamables)
+  end
+end

data/app/javascript/turbo/cable.js

@@ -0,0 +1,16 @@
+let consumer
+
+export async function getConsumer() {
+  if (consumer) return consumer
+  const { createConsumer } = await import("@rails/actioncable/src")
+  return setConsumer(createConsumer())
+}
+
+export function setConsumer(newConsumer) {
+  return consumer = newConsumer
+}
+
+export async function subscribeTo(channel, mixin) {
+  const { subscriptions } = await getConsumer()
+  return subscriptions.create(channel, mixin)
+}

data/app/javascript/turbo/cable_stream_source_element.js

@@ -0,0 +1,27 @@
+import { connectStreamSource, disconnectStreamSource } from "@hotwired/turbo"
+import { subscribeTo } from "./cable"
+
+class TurboCableStreamSourceElement extends HTMLElement {
+  async connectedCallback() {
+    connectStreamSource(this)
+    this.subscription = subscribeTo(this.channel, { received: this.dispatchMessageEvent.bind(this) })
+  }
+
+  disconnectedCallback() {
+    disconnectStreamSource(this)
+    if (this.subscription) this.subscription.unsubscribe()
+  }
+
+  dispatchMessageEvent(data) {
+    const event = new MessageEvent("message", { data })
+    return this.dispatchEvent(event)
+  }
+
+  get channel() {
+    const channel = this.getAttribute("channel")
+    const signed_stream_name = this.getAttribute("signed-stream-name")
+    return { channel, signed_stream_name }
+  }
+}
+
+customElements.define("turbo-cable-stream-source", TurboCableStreamSourceElement)

data/app/javascript/turbo/index.js

@@ -0,0 +1,3 @@
+import "./cable_stream_source_element"
+export * as Turbo from "@hotwired/turbo"
+export * as cable from "./cable"

data/app/jobs/turbo/streams/action_broadcast_job.rb

@@ -0,0 +1,6 @@
+# The job that powers all the <tt>broadcast_$action_later</tt> broadcasts available in <tt>Turbo::Streams::Broadcasts</tt>.
+class Turbo::Streams::ActionBroadcastJob < ActiveJob::Base
+  def perform(stream, action:, target:, **rendering)
+    Turbo::StreamsChannel.broadcast_action_to stream, action: action, target: target, **rendering
+  end
+end

data/app/jobs/turbo/streams/broadcast_job.rb

@@ -0,0 +1,7 @@
+# The job that powers the <tt>broadcast_render_later_to</tt> available in <tt>Turbo::Streams::Broadcasts</tt> for rendering
+# turbo stream templates.
+class Turbo::Streams::BroadcastJob < ActiveJob::Base
+  def perform(stream, **rendering)
+    Turbo::StreamsChannel.broadcast_render_to stream, **rendering
+  end
+end

data/app/models/concerns/turbo/broadcastable.rb

@@ -0,0 +1,236 @@
+# Turbo streams can be broadcast directly from models that include this module (this is automatically done for Active Records).
+# This makes it convenient to execute both synchronous and asynchronous updates, and render directly from callbacks in models
+# or from controllers or jobs that act on those models. Here's an example:
+#
+#   class Clearance < ApplicationRecord
+#     belongs_to :petitioner, class_name: "Contact"
+#     belongs_to :examiner,   class_name: "User"
+#
+#     after_create_commit :broadcast_later
+#
+#     private
+#       def broadcast_later
+#         broadcast_prepend_later_to examiner.identity, :clearances
+#       end
+#   end
+#
+# This is an example from [HEY](https://hey.com), and the clearance is the model that drives
+# [the screener](https://hey.com/features/the-screener/), which gives users the power to deny first-time senders (petitioners)
+# access to their attention (as the examiner). When a new clearance is created upon receipt of an email from a first-time
+# sender, that'll trigger the call to broadcast_later, which in turn invokes <tt>broadcast_prepend_later_to</tt>.
+#
+# That method enqueues a <tt>Turbo::Streams::ActionBroadcastJob</tt> for the prepend, which will render the partial for clearance
+# (it knows which by calling Clearance#to_partial_path, which in this case returns <tt>clearances/_clearance.html.erb</tt>),
+# send that to all users that have subscribed to updates (using <tt>turbo_stream_from(examiner.identity, :clearances)</tt> in a view)
+# using the <tt>Turbo::StreamsChannel</tt> under the stream name derived from <tt>[ examiner.identity, :clearances ]</tt>,
+# and finally prepend the result of that partial rendering to the target identified with the dom id "clearances"
+# (which is derived by default from the plural model name of the model, but can be overwritten).
+#
+# There are four basic actions you can broadcast: <tt>remove</tt>, <tt>replace</tt>, <tt>append</tt>, and
+# <tt>prepend</tt>. As a rule, you should use the <tt>_later</tt> versions of everything except for remove when broadcasting
+# within a real-time path, like a controller or model, since all those updates require a rendering step, which can slow down
+# execution. You don't need to do this for remove, since only the dom id for the model is used.
+#
+# In addition to the four basic actions, you can also use <tt>broadcast_render_later</tt> or
+# <tt>broadcast_render_later_to</tt> to render a turbo stream template with multiple actions.
+module Turbo::Broadcastable
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    # Configures the model to broadcast creates, updates, and destroys to a stream name derived at runtime by the
+    # <tt>stream</tt> symbol invocation. By default, the creates are appended to a dom id target name derived from
+    # the model's plural name. The insertion can also be made to be a prepend by overwriting <tt>insertion</tt> and
+    # the target dom id overwritten by passing <tt>target</tt>. Examples:
+    #
+    #   class Message < ApplicationRecord
+    #     belongs_to :board
+    #     broadcasts_to :board
+    #   end
+    #
+    #   class Message < ApplicationRecord
+    #     belongs_to :board
+    #     broadcasts_to ->(message) { [ message.board, :messages ] }, inserts_by: :prepend, target: "board_messages"
+    #   end
+    def broadcasts_to(stream, inserts_by: :append, target: model_name.plural)
+      after_create_commit  -> { broadcast_action_later_to stream.try(:call, self) || send(stream), action: inserts_by, target: target }
+      after_update_commit  -> { broadcast_replace_later_to stream.try(:call, self) || send(stream) }
+      after_destroy_commit -> { broadcast_remove_to stream.try(:call, self) || send(stream) }
+    end
+
+    # Same as <tt>#broadcasts_to</tt>, but the designated stream is automatically set to the current model.
+    def broadcasts(inserts_by: :append, target: model_name.plural)
+      after_create_commit  -> { broadcast_action_later action: inserts_by, target: target }
+      after_update_commit  -> { broadcast_replace_later }
+      after_destroy_commit -> { broadcast_remove }
+    end
+  end
+
+  # Remove this broadcastable model from the dom for subscribers of the stream name identified by the passed streamables.
+  # Example:
+  #
+  #   # Sends <turbo-stream action="remove" target="clearance_5"></turbo-stream> to the stream named "identity:2:clearances"
+  #   clearance.broadcast_remove_to examiner.identity, :clearances
+  def broadcast_remove_to(*streamables)
+    Turbo::StreamsChannel.broadcast_remove_to *streamables, target: self
+  end
+
+  # Same as <tt>#broadcast_remove_to</tt>, but the designated stream is automatically set to the current model.
+  def broadcast_remove
+    broadcast_remove_to self
+  end
+
+  # Replace this broadcastable model in the dom for subscribers of the stream name identified by the passed
+  # <tt>streamables</tt>. The rendering parameters can be set by appending named arguments to the call. Examples:
+  #
+  #   # Sends <turbo-stream action="replace" target="clearance_5"><template><div id="clearance_5">My Clearance</div></template></turbo-stream>
+  #   # to the stream named "identity:2:clearances"
+  #   clearance.broadcast_replace_to examiner.identity, :clearances
+  #
+  #   # Sends <turbo-stream action="replace" target="clearance_5"><template><div id="clearance_5">Other partial</div></template></turbo-stream>
+  #   # to the stream named "identity:2:clearances"
+  #   clearance.broadcast_replace_to examiner.identity, :clearances, partial: "clearances/other_partial", locals: { a: 1 }
+  def broadcast_replace_to(*streamables, **rendering)
+    Turbo::StreamsChannel.broadcast_replace_to *streamables, target: self, **broadcast_rendering_with_defaults(rendering)
+  end
+
+  # Same as <tt>#broadcast_replace_to</tt>, but the designated stream is automatically set to the current model.
+  def broadcast_replace(**rendering)
+    broadcast_replace_to self, **rendering
+  end
+
+  # Append a rendering of this broadcastable model to the target identified by it's dom id passed as <tt>target</tt>
+  # for subscribers of the stream name identified by the passed <tt>streamables</tt>. The rendering parameters can be set by
+  # appending named arguments to the call. Examples:
+  #
+  #   # Sends <turbo-stream action="append" target="clearances"><template><div id="clearance_5">My Clearance</div></template></turbo-stream>
+  #   # to the stream named "identity:2:clearances"
+  #   clearance.broadcast_append_to examiner.identity, :clearances, target: "clearances"
+  #
+  #   # Sends <turbo-stream action="append" target="clearances"><template><div id="clearance_5">Other partial</div></template></turbo-stream>
+  #   # to the stream named "identity:2:clearances"
+  #   clearance.broadcast_append_to examiner.identity, :clearances, target: "clearances",
+  #     partial: "clearances/other_partial", locals: { a: 1 }
+  def broadcast_append_to(*streamables, target: broadcast_target_default, **rendering)
+    Turbo::StreamsChannel.broadcast_append_to *streamables, target: target, **broadcast_rendering_with_defaults(rendering)
+  end
+
+  # Same as <tt>#broadcast_append_to</tt>, but the designated stream is automatically set to the current model.
+  def broadcast_append(target: broadcast_target_default, **rendering)
+    broadcast_append_to self, target: target, **rendering
+  end
+
+  # Prepend a rendering of this broadcastable model to the target identified by it's dom id passed as <tt>target</tt>
+  # for subscribers of the stream name identified by the passed <tt>streamables</tt>. The rendering parameters can be set by
+  # appending named arguments to the call. Examples:
+  #
+  #   # Sends <turbo-stream action="prepend" target="clearances"><template><div id="clearance_5">My Clearance</div></template></turbo-stream>
+  #   # to the stream named "identity:2:clearances"
+  #   clearance.broadcast_prepend_to examiner.identity, :clearances, target: "clearances"
+  #
+  #   # Sends <turbo-stream action="prepend" target="clearances"><template><div id="clearance_5">Other partial</div></template></turbo-stream>
+  #   # to the stream named "identity:2:clearances"
+  #   clearance.broadcast_prepend_to examiner.identity, :clearances, target: "clearances",
+  #     partial: "clearances/other_partial", locals: { a: 1 }
+  def broadcast_prepend_to(*streamables, target: broadcast_target_default, **rendering)
+    Turbo::StreamsChannel.broadcast_prepend_to *streamables, target: target, **broadcast_rendering_with_defaults(rendering)
+  end
+
+  # Same as <tt>#broadcast_append_to</tt>, but the designated stream is automatically set to the current model.
+  def broadcast_prepend(target: broadcast_target_default, **rendering)
+    broadcast_prepend_to self, target: target, **rendering
+  end
+
+  # Broadcast a named <tt>action</tt>, allowing for dynamic dispatch, instead of using the concrete action methods. Examples:
+  #
+  #   # Sends <turbo-stream action="prepend" target="clearances"><template><div id="clearance_5">My Clearance</div></template></turbo-stream>
+  #   # to the stream named "identity:2:clearances"
+  #   clearance.broadcast_action_to examiner.identity, :clearances, action: :prepend, target: "clearances"
+  def broadcast_action_to(*streamables, action:, target: broadcast_target_default, **rendering)
+    Turbo::StreamsChannel.broadcast_action_to(*streamables, action: action, target: target, **broadcast_rendering_with_defaults(rendering))
+  end
+
+  # Same as <tt>#broadcast_action_to</tt>, but the designated stream is automatically set to the current model.
+  def broadcast_action(action, target: broadcast_target_default, **rendering)
+    broadcast_action_to self, action: action, target: target, **rendering
+  end
+
+
+  # Same as <tt>broadcast_replace_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
+  def broadcast_replace_later_to(*streamables, **rendering)
+    Turbo::StreamsChannel.broadcast_replace_later_to *streamables, target: self, **broadcast_rendering_with_defaults(rendering)
+  end
+
+  # Same as <tt>#broadcast_replace_later_to</tt>, but the designated stream is automatically set to the current model.
+  def broadcast_replace_later(**rendering)
+    broadcast_replace_later_to self, **rendering
+  end
+
+  # Same as <tt>broadcast_append_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
+  def broadcast_append_later_to(*streamables, target: broadcast_target_default, **rendering)
+    Turbo::StreamsChannel.broadcast_append_later_to *streamables, target: target, **broadcast_rendering_with_defaults(rendering)
+  end
+
+  # Same as <tt>#broadcast_append_later_to</tt>, but the designated stream is automatically set to the current model.
+  def broadcast_append_later(target: broadcast_target_default, **rendering)
+    broadcast_append_later_to self, target: target, **rendering
+  end
+
+  # Same as <tt>broadcast_prepend_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
+  def broadcast_prepend_later_to(*streamables, target: broadcast_target_default, **rendering)
+    Turbo::StreamsChannel.broadcast_prepend_later_to *streamables, target: target, **broadcast_rendering_with_defaults(rendering)
+  end
+
+  # Same as <tt>#broadcast_prepend_later_to</tt>, but the designated stream is automatically set to the current model.
+  def broadcast_prepend_later(target: broadcast_target_default, **rendering)
+    broadcast_prepend_later_to self, target: target, **rendering
+  end
+
+  # Same as <tt>broadcast_action_later_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
+  def broadcast_action_later_to(*streamables, action:, target: broadcast_target_default, **rendering)
+    Turbo::StreamsChannel.broadcast_action_later_to(*streamables, action: action, target: target, **broadcast_rendering_with_defaults(rendering))
+  end
+
+  # Same as <tt>#broadcast_action_later_to</tt>, but the designated stream is automatically set to the current model.
+  def broadcast_action_later(action:, target: broadcast_target_default, **rendering)
+    broadcast_action_later_to self, action: action, target: target, **rendering
+  end
+
+
+  # Render a turbo stream template asynchronously with this broadcastable model passed as the local variable using a
+  # <tt>Turbo::Streams::BroadcastJob</tt>. Example:
+  #
+  #   # Template: entries/_entry.turbo_stream.erb
+  #   <%= turbo_stream.remove entry %>
+  #
+  #   <%= turbo_stream.append "entries" do %>
+  #     <%= render partial: "entries/entry", locals: { entry: entry }, formats: [ :html ] %>
+  #   <% end if entry.active? %>
+  #
+  #   # Sends:
+  #   #   <turbo-stream action="remove" target="entry_5"></turbo-stream>
+  #   #   <turbo-stream action="append" target="entries"><template><div id="entry_5">My Entry</div></template></turbo-stream>
+  #   # to the stream named "entry:5"
+  #   entry.broadcast_render_later
+  def broadcast_render_later(**rendering)
+    broadcast_render_later_to self, **rendering
+  end
+
+  # Same as <tt>broadcast_prepend_to</tt> but run with the added option of naming the stream using the passed
+  # <tt>streamables</tt>.
+  def broadcast_render_later_to(*streamables, **rendering)
+    Turbo::StreamsChannel.broadcast_render_later_to *streamables, **broadcast_rendering_with_defaults(rendering)
+  end
+
+
+  private
+    def broadcast_target_default
+      model_name.plural
+    end
+
+    def broadcast_rendering_with_defaults(options)
+      options.tap do |o|
+        o[:locals]    = (o[:locals] || {}).reverse_merge!(model_name.singular.to_sym => self)
+        o[:partial] ||= to_partial_path
+      end
+    end
+end