diff --git a/lib/phoenix_live_view.ex b/lib/phoenix_live_view.ex index 6b76c81db2..142d5aaa65 100644 --- a/lib/phoenix_live_view.ex +++ b/lib/phoenix_live_view.ex @@ -1541,6 +1541,7 @@ defmodule Phoenix.LiveView do @doc ~S""" Assigns a new stream to the socket or inserts items into an existing stream. + Returns an updated `socket`. Streams are a mechanism for managing large collections on the client without keeping the resources on the server. @@ -1657,6 +1658,7 @@ defmodule Phoenix.LiveView do Now `stream_insert/3` and `stream_delete/3` may be issued and new rows will be inserted or deleted from the client. """ + @spec stream(%Socket{}, name :: atom | String.t, items :: Enumerable.t, opts :: Keyword.t) :: %Socket{} def stream(%Socket{} = socket, name, items, opts \\ []) do if Keyword.has_key?(opts, :dom_id) do IO.warn( @@ -1697,7 +1699,10 @@ defmodule Phoenix.LiveView do def update(assigns, socket) do {:ok, stream(socket, :songs, ...)} end + + Returns an updated `socket`. """ + @spec stream_configure(%Socket{}, name :: atom | String.t, opts :: Keyword.t) :: %Socket{} def stream_configure(%Socket{} = socket, name, opts) when is_list(opts) do new_socket = ensure_streams(socket) @@ -1724,6 +1729,8 @@ defmodule Phoenix.LiveView do @doc """ Inserts a new item or updates an existing item in the stream. + Returns an updated `socket`. + By default, the item is appended to the parent DOM container. The `:at` option may be provided to insert or update an item to a particular index in the collection on the client. @@ -1765,6 +1772,7 @@ defmodule Phoenix.LiveView do See `stream_delete/3` for more information on deleting items. """ + @spec stream_insert(%Socket{}, name :: atom | String.t, item :: any, opts :: Keyword.t) :: %Socket{} def stream_insert(%Socket{} = socket, name, item, opts \\ []) do at = Keyword.get(opts, :at, -1) limit = Keyword.get(opts, :limit) @@ -1789,7 +1797,10 @@ defmodule Phoenix.LiveView do See `stream_delete_by_dom_id/3` to remove an item without requiring the original data structure. + + Returns an updated `socket`. """ + @spec stream_delete(%Socket{}, name :: atom | String.t, item :: any) :: %Socket{} def stream_delete(%Socket{} = socket, name, item) do update_stream(socket, name, &LiveStream.delete_item(&1, item)) end @@ -1797,6 +1808,8 @@ defmodule Phoenix.LiveView do @doc ~S''' Deletes an item from the stream given its computed DOM id. + Returns an updated `socket`. + Behaves just like `stream_delete/3`, but accept the precomputed DOM id, which allows deleting from a stream without fetching or building the original stream data structure. @@ -1823,6 +1836,7 @@ defmodule Phoenix.LiveView do {:noreply, stream_delete_by_dom_id(socket, :songs, dom_id)} end ''' + @spec stream_delete_by_dom_id(%Socket{}, name :: atom | String.t, id :: String.t) :: %Socket{} def stream_delete_by_dom_id(%Socket{} = socket, name, id) do update_stream(socket, name, &LiveStream.delete_item_by_dom_id(&1, id)) end