fix(api): add more robust api state detection for stream/match

Author: asmodeus812

lua/fuzzy/match.lua

@@ -247,6 +247,18 @@ function Match:_match_worker()
     end
 end
 
+--- Returns true if the matcher is considered finalized and no longer processing data in-flight, and there is a valid set of data present for consumption produced by the matcher
+--- @return boolean True if the matched results data is ready to be consumed by the client
+function Match:isvalid()
+    return not self:running() and self.results ~= nil and #self.results > 0 and self.results[1] ~= nil and #self.results[1] >= 0
+end
+
+--- Checks if the match has matched any entries ready for consumption
+--- @return boolean True if the matcher has no entries matched, false otherwise.
+function Match:isempty()
+    return self:isvalid() and #self.results[1] == 0
+end
+
 --- Checks if there is an ongoing matching operation, i.e., if the timer is active, which indicates that matching is in progress.
 --- @return boolean True if a matching operation is currently running, false otherwise.
 function Match:running()

lua/fuzzy/picker.lua

@@ -320,8 +320,7 @@ function Picker:_input_prompt()
             -- in interactive mode we need to restart the stream with the new query, so that the command can produce results
             -- based on the query, for example when using find -name <query>, we do not perform fuzzy matching on the stream
             -- in interactive mode, this is done on demand in the second stage
-            local content = self._state.content
-            assert(type(content) ~= "table")
+            assert(self:_is_dynamic())
 
             if type(query) == "string" and #query > 0 then
                 -- when interactive string it means that the string is an argument placeholder, that should be replaced
@@ -355,15 +354,26 @@ function Picker:_input_prompt()
             -- the interactive stage, that might have been matched
             self:_hide_stage()
             self:_clear_stage()
-        elseif not self.stream:running() then
+        else
+            local data = nil
+            if self:_is_dynamic() then
+                if not self.stream:isvalid() then
+                    return
+                end
+                data = assert(self.stream.results)
+            elseif self:_is_static() then
+                data = assert(self._state.content)
+            else
+                assert(false, "unknown picker state")
+            end
+
             -- when there is a query we need to match against it, in this scenario the picker is non-interactive, there are
             -- two options, either it was configured to use a stream or a user provided table of entries - strings, or other
             -- tables
-            local data = assert(self.stream.results or self._state.content)
             if #data > 0 and type(query) == "string" and #query > 0 then
                 self.match:match(data, query, function(matching)
                     if matching == nil then
-                        if not self.match.results or #self.match.results == 0 or #self.match.results[1] == 0 then
+                        if not self.match:isvalid() or self.match:isempty() then
                             self.select:list(
                                 utils.EMPTY_TABLE,
                                 utils.EMPTY_TABLE
@@ -405,11 +415,11 @@ function Picker:_create_stage()
             if query == nil then
                 self:_close_stage()
                 self:_close_picker()
-            elseif self.stream.results ~= nil then
+            elseif self.stream:isvalid() then
                 if #self.stream.results > 0 and type(query) == "string" and #query > 0 then
                     stage.match:match(self.stream.results, query, function(matching)
                         if matching == nil then
-                            if not stage.match.results or #stage.match.results == 0 or #stage.match.results[1] == 0 then
+                            if not stage.match:isvalid() and stage.match:isempty() then
                                 stage.select:list(
                                     utils.EMPTY_TABLE,
                                     utils.EMPTY_TABLE
@@ -507,7 +517,7 @@ function Picker:_toggle_stage()
         self:_hide_picker()
         stage.select:open()
 
-        if stage.select:isempty() and self.stream.results then
+        if stage.select:isempty() and self.stream:isvalid() then
             stage.select:list(
                 self.stream.results,
                 nil -- no highlights
@@ -619,7 +629,7 @@ function Picker:_flush_interactive()
     return utils.debounce_callback(self._options.stream_debounce, function(_, all)
         if all == nil then
             -- Stream finished: if it produced nothing, explicitly render an empty list, then signal completion.
-            if not self.stream.results or #self.stream.results == 0 then
+            if not self.stream:isvalid() then
                 self.select:list(
                     utils.EMPTY_TABLE,
                     utils.EMPTY_TABLE
@@ -644,16 +654,23 @@ function Picker:_flush_direct()
         if all == nil then
             -- Stream finished: if it produced nothing, explicitly render an empty list, then signal to the list renderer for content
             -- delivery completion.  there is also a case
-            if not self.stream.results or #self.stream.results == 0 then
+            if not self.stream:isvalid() then
                 self.select:list(
                     utils.EMPTY_TABLE,
                     utils.EMPTY_TABLE
                 )
                 self.select:status("0/0")
             end
+
             -- Final nil list marks end of streaming: Select stops incremental updates and treats the list as stable until
             -- new data arrives (or re-open).
             self.select:list(nil, nil)
+
+            -- manually prime the input for matching, in case a query has arrived right at the end of the stream, attempt to run a match, in
+            -- case more input arrives this call will be de-bounced by the future calls and effectively be a no-op which is okay
+            local options = self.select:options()
+            local query = self.select:query()
+            options.prompt_input(query)
         else
             -- Pull the current state query, sync we need to have an overview of the query value always, every time new accumulation of items
             -- arrives from the stream we have to re-roder them all and re-match them in accordance to the query
@@ -664,7 +681,7 @@ function Picker:_flush_direct()
             if #all > 0 and type(query) == "string" and #query > 0 then
                 self.match:match(all, query, function(matching)
                     if matching == nil then
-                        if not self.match.results or #self.match.results == 0 or #self.match.results[1] == 0 then
+                        if not self.match:isvalid() or self.match:isempty() then
                             self.select:list(
                                 utils.EMPTY_TABLE,
                                 utils.EMPTY_TABLE
@@ -707,6 +724,14 @@ function Picker:_is_valid()
     )
 end
 
+function Picker:_is_dynamic()
+    return type(self._state.content) ~= "table"
+end
+
+function Picker:_is_static()
+    return type(self._state.content) == "table"
+end
+
 function Picker:_is_interactive()
     local interactive = self._options.interactive
     return interactive ~= nil and interactive ~= false
@@ -797,11 +822,11 @@ function Picker:open()
         end
         self.select:open()
 
-        if type(self._state.content) ~= "table" then
+        if self:_is_dynamic() then
             -- when a string or a function is provided the content is expected to be a command that produces output, or a function
             -- that produces output by calling a callback method for each entry in the stream
             assert(type(self._state.content) == "string" or type(self._state.content) == "function")
-            if (needs_rerun or not self.stream.results) and not self:_is_interactive() then
+            if (needs_rerun or not self.stream:isvalid()) and not self:_is_interactive() then
                 -- in case we need to re-run the picker or the stream itself was destroyed, having no-results implies
                 -- that stream requires to be re-started, to obtain results and then fill the select interface
                 self.stream:start(self._state.content, {
@@ -811,7 +836,7 @@ function Picker:open()
                     callback = self:_flush_direct(),
                     transform = self._options.stream_map,
                 })
-            elseif self.stream.results and self.select:isempty() then
+            elseif self.stream:isvalid() and self.select:isempty() then
                 -- in case there are valid results in the stream, just fill the select interface, having results here
                 -- means the stream was not destroyed and it still persistent.
                 self.select:list(
@@ -949,7 +974,7 @@ function Picker.new(opts)
     if self:_is_interactive() then
         -- ensure that picker is not marked interactive when a table
         -- static content is provided for the picker, otherwise fail
-        assert(type(self._options.content) ~= "table")
+        assert(self:_is_dynamic())
     end
 
     self.match = Match.new({

lua/fuzzy/select.lua

@@ -2419,6 +2419,28 @@ function Select:send_locliset(callback)
     self:send_fixlist("loclist", callback)
 end
 
+--- Checks if the selection interface is currently open, this is determined by checking if both the prompt and list windows are valid.
+--- @return boolean True if the selection interface is open, false otherwise.
+function Select:isopen()
+    local prompt = self.prompt_window and vim.api.nvim_win_is_valid(self.prompt_window)
+    local list = self.list_window and vim.api.nvim_win_is_valid(self.list_window)
+    return list ~= nil and prompt ~= nil and list and prompt
+end
+
+--- Checks if the selection interface is valid, meaning that it has been initialized/opened at least once and has not been destroyed by calling the `close` method which would invalidate its curent state
+--- @return boolean True if the select interface is still valid, false otherwise.
+function Select:isvalid()
+    local prompt = self.prompt_buffer and vim.api.nvim_buf_is_valid(self.prompt_buffer)
+    local list = self.list_buffer and vim.api.nvim_buf_is_valid(self.list_buffer)
+    return list ~= nil and prompt ~= nil and list and prompt
+end
+
+--- Checks if the selection interface is showing any entries, the entries can be rendered or set using the `list` method, which renders the specified entries into the list.
+--- @return boolean True if the list is empty, false otherwise.
+function Select:isempty()
+    return not self._state.entries or #self._state.entries == 0
+end
+
 --- Gets the current query from the prompt input. The query is updated on each input change in the prompt. It is not extracted directly from the prompt buffer on-demand but is captured with each input change using TextChangedI and TextChanged autocmd events.
 --- @return string The current query string, the query will never be nil, otherwise that represents invalid state of the selection interface.
 function Select:query()
@@ -2447,28 +2469,6 @@ function Select:clear()
     self:_clear_view(false)
 end
 
---- Checks if the selection interface is showing any entries, the entries can be rendered or set using the `list` method, which renders the specified entries into the list.
---- @return boolean True if the list is empty, false otherwise.
-function Select:isempty()
-    return not self._state.entries or #self._state.entries == 0
-end
-
---- Checks if the selection interface is currently open, this is determined by checking if both the prompt and list windows are valid.
---- @return boolean True if the selection interface is open, false otherwise.
-function Select:isopen()
-    local prompt = self.prompt_window and vim.api.nvim_win_is_valid(self.prompt_window)
-    local list = self.list_window and vim.api.nvim_win_is_valid(self.list_window)
-    return list ~= nil and prompt ~= nil and list and prompt
-end
-
---- Checks if the selection interface is valid, meaning that it has been initialized/opened at least once and has not been destroyed by calling the `close` method which would invalidate its curent state
---- @return boolean True if the select interface is still valid, false otherwise.
-function Select:isvalid()
-    local prompt = self.prompt_buffer and vim.api.nvim_buf_is_valid(self.prompt_buffer)
-    local list = self.list_buffer and vim.api.nvim_buf_is_valid(self.list_buffer)
-    return list ~= nil and prompt ~= nil and list and prompt
-end
-
 -- Render a list of entries in the list window, with optional highlighting positions. If entries is nil, it will re-render the current list fully with existing entries and positions. Sending nil for both parameters signals to the interface that the streaming of entries is complete and it should finalize the rendering. This method is optimized to handle large lists of entries efficiently by rendering only the visible portion of the list and updating it as needed around the cursor position. The list is incrementally updated as new entries are provided, allowing for a smooth and responsive user experience even with large datasets.
 -- @param entries? any[]|string[]|nil The list of entries to display.
 -- @param positions? integer[][]|nil The list of positions for highlighting
@@ -2927,7 +2927,7 @@ end
 --- @class SelectOptions
 --- @inlinedoc
 --- @field prompt_list? boolean|fun()|any[] Whether to show the list window or a function to provide initial entries.
---- @field prompt_input? boolean|fun() Whether to show the input prompt, when function is provided it is used as the input callback.
+--- @field prompt_input? boolean|fun(string?) Whether to show the input prompt, when function is provided it is used as the input callback and the query is passed to it.
 --- The callback may return a list of entries directly, or a table with `entries` and optional `positions` for synchronous updates.
 --- @field prompt_headers? table|string|nil Headers to display above the prompt input, can be a string or a table of strings or string/highlight pairs, where each inner table represents a block of header entries.
 --- @field prompt_query? string|nil Initial query to populate the prompt input with. If provided, the prompt input must also be enabled. The query will be set in the prompt input and the input callback will be invoked with this initial query.

lua/fuzzy/stream.lua

@@ -340,6 +340,18 @@ function Stream:_stop_streaming()
     end
 end
 
+--- Returns true if the stream is considered finalized and no longer processing data in-flight, and there is a valid set of data present for consumption produced by the stream
+--- @return boolean True if the stream results data is ready to be consumed by the client
+function Stream:isvalid()
+    return not self:running() and self.results ~= nil and #self.results >= 0
+end
+
+--- Checks if the stream has accumulated any entries ready for consumption
+--- @return boolean True if the matcher has no entries accumulated, false otherwise.
+function Stream:isempty()
+    return self:isvalid() and #self.results == 0
+end
+
 --- Returns true if the stream is started or is already running, i.e. has been started and not yet stopped, exited or aborted, false otherwise
 --- @return boolean True if the stream is started or running, false otherwise
 function Stream:running()
@@ -353,19 +365,6 @@ function Stream:options()
     return assert(self._options)
 end
 
--- Destroys the stream and any pending state that is currently being allocated into the stream, note that this is done automatically for
--- ephemeral streams when a new stream is re-started the resources for the previous ones are invalidated
-function Stream:destroy()
-    self:_close_stream()
-    self:_destroy_stream()
-end
-
---- Stops the stream if it is running and finalizes the current buffered results without destroying them
-function Stream:stop()
-    self:_close_stream()
-    self:_stop_streaming()
-end
-
 --- Waits for the stream to finish, or until the timeout is reached
 --- @param timeout integer|nil The maximum time to wait in milliseconds, defaults to the timeout specified in the options, or utils.MAX_TIMEOUT
 --- @return string[]|nil The results accumulated so far, or nil if the timeout was reached
@@ -381,6 +380,19 @@ function Stream:wait(timeout)
     return self.results
 end
 
+-- Destroys the stream and any pending state that is currently being allocated into the stream, note that this is done automatically for
+-- ephemeral streams when a new stream is re-started the resources for the previous ones are invalidated
+function Stream:destroy()
+    self:_close_stream()
+    self:_destroy_stream()
+end
+
+--- Stops the stream if it is running and finalizes the current buffered results without destroying them
+function Stream:stop()
+    self:_close_stream()
+    self:_stop_streaming()
+end
+
 --- @class StreamStartOpts
 --- @field cwd? string The current working directory to run the command in, defaults to the current working directory of Neovim
 --- @field args? string[] The arguments to pass to the command, defaults to an empty table