feat: add type annotations for plenary.curl

Author: delphinus

lua/plenary/curl.lua

@@ -1,3 +1,5 @@
+-- luacheck: push ignore 631
+
 --[[
 Curl Wrapper
 
@@ -28,6 +30,9 @@ see test/plenary/curl_spec.lua for examples.
 author = github.com/tami5
 ]]
 --
+---@alias PlenaryCurlMethod fun(url: string|PlenaryCurlOptions, opts?: PlenaryCurlOptions): PlenaryCurlResponse|PlenaryJob|string[]
+
+-- luacheck: pop
 
 local util, parse = {}, {}
 
@@ -40,6 +45,8 @@ local P = require "plenary.path"
 -- Utils ----------------------------------------------------
 -------------------------------------------------------------
 
+---@param str string|integer
+---@return string|integer
 util.url_encode = function(str)
   if type(str) ~= "number" then
     str = str:gsub("\r?\n", "\r\n")
@@ -53,12 +60,20 @@ util.url_encode = function(str)
   end
 end
 
+---@param kv table<string, string>
+---@param prefix string
+---@param sep string
+---@return string[]
 util.kv_to_list = function(kv, prefix, sep)
   return vim.tbl_flatten(F.kv_map(function(kvp)
     return { prefix, kvp[1] .. sep .. kvp[2] }
   end, kv))
 end
 
+---@param kv table<string, string>
+---@param sep? string
+---@param kvsep string
+---@return string
 util.kv_to_str = function(kv, sep, kvsep)
   return F.join(
     F.kv_map(function(kvp)
@@ -68,6 +83,7 @@ util.kv_to_str = function(kv, sep, kvsep)
   )
 end
 
+---@return { [1]: string, [2]: string }
 util.gen_dump_path = function()
   local path
   local id = string.gsub("xxxx4xxx", "[xy]", function(l)
@@ -86,15 +102,21 @@ end
 -- Parsers ----------------------------------------------------
 ---------------------------------------------------------------
 
+---comment
+---@param t? table<string, string>
+---@return string[]?
 parse.headers = function(t)
   if not t then
     return
   end
+  ---@param str string
+  ---@return string
   local upper = function(str)
     return string.gsub(" " .. str, "%W%l", string.upper):sub(2)
   end
   return util.kv_to_list(
     (function()
+      ---@type table<string, string>
       local normilzed = {}
       for k, v in pairs(t) do
         normilzed[upper(k:gsub("_", "%-"))] = v
@@ -106,13 +128,17 @@ parse.headers = function(t)
   )
 end
 
+---@param t? table<string, string>
+---@return string[]?
 parse.data_body = function(t)
   if not t then
     return
   end
   return util.kv_to_list(t, "-d", "=")
 end
 
+---@param xs? string|table<string, string>
+---@return string[]?
 parse.raw_body = function(xs)
   if not xs then
     return
@@ -124,20 +150,26 @@ parse.raw_body = function(xs)
   end
 end
 
+---@param t? table<string, string>
+---@return string[]?
 parse.form = function(t)
   if not t then
     return
   end
   return util.kv_to_list(t, "-F", "=")
 end
 
+---@param t? table<string, string>
+---@return string?
 parse.curl_query = function(t)
   if not t then
     return
   end
   return util.kv_to_str(t, "&", "=")
 end
 
+---@param s? string
+---@return { [1]: "-I"|"-X", [2]: string? }?
 parse.method = function(s)
   if not s then
     return
@@ -149,39 +181,50 @@ parse.method = function(s)
   end
 end
 
+---@param p? string
+---@return { [1]: "-d", [2]: string }?
 parse.file = function(p)
   if not p then
     return
   end
   return { "-d", "@" .. P.expand(P.new(p)) }
 end
 
+---@param xs string|table<string, string>
+---@return { [1]: "-u", [2]: string }?
 parse.auth = function(xs)
   if not xs then
     return
   end
   return { "-u", type(xs) == "table" and util.kv_to_str(xs, nil, ":") or xs }
 end
 
+---@param xs string
+---@param q table<string, string>
+---@return string?
 parse.url = function(xs, q)
   if not xs then
     return
   end
-  q = parse.curl_query(q)
+  local query = parse.curl_query(q)
   if type(xs) == "string" then
-    return q and xs .. "?" .. q or xs
+    return query and xs .. "?" .. query or xs
   elseif type(xs) == "table" then
     error "Low level URL definition is not supported."
   end
 end
 
+---@param s string?
+---@return { [1]: "-H", [2]: string }?
 parse.accept_header = function(s)
   if not s then
     return
   end
   return { "-H", "Accept: " .. s }
 end
 
+---@param s string?
+---@return { [1]: string }?
 parse.http_version = function(s)
   if not s then
     return
@@ -197,9 +240,36 @@ end
 
 -- Parse Request -------------------------------------------
 ------------------------------------------------------------
+---@class PlenaryCurlOptions
+---@field auth? string|table<string, string> Basic request auth, 'user:pass', or {"user", "pass"}
+---@field body? string|string[] The request body
+---@field dry_run? boolean whether to return the args to be ran through curl.
+---@field form? table<string, string> request form
+---@field http_version? string HTTP version to use: 'HTTP/0.9', 'HTTP/1.0', 'HTTP/1.1', 'HTTP/2', or 'HTTP/3'
+---@field insecure? boolean Allow insecure server connections
+---@field output? string where to download something.
+---@field proxy? string [protocol://]host[:port] Use this proxy
+---@field query? table<string, string> url query, append after the url
+---@field raw? string[] any additonal curl args, it must be an array/list.
+---@field timeout? integer request timeout in mseconds
+---@field url? string The url to make the request to.
+---@field accept? string
+---@field callback? fun(response: PlenaryCurlResponse)
+---@field compressed? boolean
+---@field data? string[]
+---@field dump? string
+---@field headers? string[]
+---@field in_file? string
+---@field method? string
+---@field on_error? fun(err: { message: string, stderr: string, exit: integer })
+---@field raw_body? string
+---@field stream? PlenaryJobCallback
+
+---@param opts PlenaryCurlOptions
+---@return string[] result, PlenaryCurlOptions opts
 parse.request = function(opts)
   if opts.body then
-    local b = opts.body
+    local b = opts.body --[[@as string|string[] ]]
     local silent_is_file = function()
       local status, result = pcall(P.is_file, P.new(b))
       return status and result
@@ -248,6 +318,16 @@ end
 
 -- Parse response ------------------------------------------
 ------------------------------------------------------------
+---@class PlenaryCurlResponse
+---@field status integer
+---@field headers string[]
+---@field body string
+---@field exit integer
+
+---@param lines string[]
+---@param dump_path string
+---@param code integer
+---@return PlenaryCurlResponse
 parse.response = function(lines, dump_path, code)
   local headers = P.readlines(dump_path)
   local status = tonumber(string.match(headers[1], "([%w+]%d+)"))
@@ -264,6 +344,8 @@ parse.response = function(lines, dump_path, code)
   }
 end
 
+---@param specs PlenaryCurlOptions
+---@return PlenaryCurlResponse|PlenaryJob|string[]
 local request = function(specs)
   local response = {}
   local args, opts = parse.request(vim.tbl_extend("force", {
@@ -276,6 +358,7 @@ local request = function(specs)
     return args
   end
 
+  ---@type PlenaryJobOptions
   local job_opts = {
     command = "curl",
     args = args,
@@ -299,7 +382,7 @@ local request = function(specs)
         error(message)
       end
     end
-    local output = parse.response(j:result(), opts.dump[2], code)
+    local output = parse.response((j:result() --[[@as string[] ]]), opts.dump[2], code)
     if opts.callback then
       return opts.callback(output)
     else
@@ -320,8 +403,21 @@ end
 
 -- Main ----------------------------------------------------
 ------------------------------------------------------------
+
+---@class PlenaryCurl
+---@field get PlenaryCurlMethod
+---@field post PlenaryCurlMethod
+---@field put PlenaryCurlMethod
+---@field head PlenaryCurlMethod
+---@field patch PlenaryCurlMethod
+---@field delete PlenaryCurlMethod
+---@field request PlenaryCurlMethod
+
+---@return PlenaryCurl
 return (function()
   local spec = {}
+  ---@param method "get"|"post"|"put"|"head"|"patch"|"delete"|"request"
+  ---@return PlenaryCurlMethod
   local partial = function(method)
     return function(url, opts)
       opts = opts or {}

lua/plenary/init.lua

@@ -2,6 +2,7 @@
 ---@class Plenary
 ---@field async PlenaryAsync
 ---@field context_manager PlenaryContextManager
+---@field curl PlenaryCurl
 ---@field functional PlenaryFunctional
 ---@field job PlenaryJob
 ---@field path PlenaryPath

tests/plenary/curl_spec.lua

@@ -84,7 +84,7 @@ describe("CURL Wrapper:", function()
         return done
       end)
 
-      eq(403, res.status, "It should return 403")
+      eq(403, res and res.status, "It should return 403")
       assert(not succ, "It should fail")
 
       vim.fn.delete(loc)