feat(fs): add vim.fs.dir()

This function is modeled after the path.dir() function from Penlight and
the luafilesystem module.

runtime/doc/lua.txt

@@ -2160,6 +2160,20 @@ basename({file})                                           *vim.fs.basename()*
                 Return: ~
                     (string) Basename of {file}
 
+dir({path})                                                     *vim.fs.dir()*
+                Return an iterator over the files and directories located in
+                {path}
+
+                Parameters: ~
+                    {path}  (string) An absolute or relative path to the
+                            directory to iterate over
+
+                Return: ~
+                    Iterator over files and directories in {path}. Each
+                    iteration yields two values: name and type. Each "name" is
+                    the basename of the file or directory relative to {path}.
+                    Type is one of "file" or "directory".
+
 dirname({file})                                             *vim.fs.dirname()*
                 Return the parent directory of the given file or directory
 

runtime/lua/vim/fs.lua

@@ -48,4 +48,17 @@ function M.basename(file)
   return vim.fn.fnamemodify(file, ':t')
 end
 
+--- Return an iterator over the files and directories located in {path}
+---
+---@param path (string) An absolute or relative path to the directory to iterate
+---            over
+---@return Iterator over files and directories in {path}. Each iteration yields
+---        two values: name and type. Each "name" is the basename of the file or
+---        directory relative to {path}. Type is one of "file" or "directory".
+function M.dir(path)
+  return function(fs)
+    return vim.loop.fs_scandir_next(fs)
+  end, vim.loop.fs_scandir(path)
+end
+
 return M

test/functional/lua/fs_spec.lua

@@ -52,4 +52,18 @@ describe('vim.fs', function()
       ]], nvim_prog))
     end)
   end)
+
+  describe('dir()', function()
+    it('works', function()
+      eq(true, exec_lua([[
+        local dir, nvim = ...
+        for name, type in vim.fs.dir(dir) do
+          if name == nvim and type == 'file' then
+            return true
+          end
+        end
+        return false
+      ]], nvim_dir, nvim_prog_basename))
+    end)
+  end)
 end)