[Feature] support returning tables in starlight plugins ffi

[k0d13]

Before Requesting

• I found no existing issue matching my feature request
• This request is related to Millennium, and not a request for a specific theme/addon

Describe the feature you'd like!

So far it seems as though starlight ffi functions can only return primtive values, as right now trying to return a table will just return null.

---@ffi
function getTable()
  return { a = 1, b = 2 }
end

const out = await backend.getTable()
//        ^? null

And then would also be nice to type these, as both the following currently are unknown

---@return { a: number, b: number }

---@class Result
---@field a number
---@field b number

---@return Result

The latter also nested classes https://discord.com/channels/1102739071085846623/1317682877839970366/1539130724987437146

Anything else?

No response

[ejalxndr]

Just leaving some doc string here while this feature is in the beta branch.

Checkout SteamClientHomebrew/PluginTemplate@bad39d5 aswell

The following features are in >=v3.5.0-beta.1, and starlight >=1.1.4

Returning a table

---@ffi
function GetLibrary()
    return {
        ok = true,
        games = {
            { id = 1, name = "A" },
            { id = 2, name = "B" },
        },
        refreshed_at = os.time(),
    }
end

const lib = await backend.GetLibrary();
console.log(lib.games[0].name); // "A"

Passing a table as an argument

---@ffi
---@param filters table
function SearchLibrary(filters)
    -- filters.installed, filters.query, etc. are already a real Lua table
    return { count = 0, results = {} }
end

await backend.SearchLibrary({ installed: true, query: "rocket" });

Nested tables (arrays and objects can mix freely)

---@ffi
function GetConfig()
    return {
        theme = "dark",
        recentIds = { 10, 42, 7 },               -- becomes a JSON array
        window = { width = 1280, height = 800 }, -- becomes a nested object
    }
end

nil/null inside a table: use cjson.null, not nil

local json = require("json")

---@ffi
function GetProfile()
    return {
        name = "player",
        avatarUrl = json.null, -- becomes `"avatarUrl": null`, not an absent key
    }
end

The same comes back the other way too, a null field in a JS-side argument object arrives in Lua as json.null, not nil:

---@ffi
---@param opts table
function SetAvatar(opts)
    if opts.avatarUrl == json.null then
        -- explicit "clear the avatar" vs. opts.avatarUrl == nil meaning "field absent"
    end
end

Empty table → {}, not []

---@ffi
function GetEmpty()
    return {}
end

await backend.GetEmpty(); // {} an empty Lua table is always treated as an object

If you need an empty array specifically, return something the array-shape check recognizes, e.g. build it with at least a throwaway convention, or just be aware {} always serializes as {}.

Values with no JSON representation get dropped, not crash the call

---@ffi
function GetMixed()
    return {
        ok = true,
        onDone = function() end, -- dropped from the object entirely
    }
end

await backend.GetMixed(); // { ok: true } "onDone" isn't there

In an array, the same case becomes null in that slot instead, so indices don't shift:
return { 1, function() end, 3 } --> [1, null, 3]
A warning is printed to the plugin's stderr log either way so it's not silent in dev.

Cyclic / too-deeply-nested tables fail cleanly

---@ffi
function GetBroken()
    local t = {}
    t.self = t
    return t
end

await backend.GetBroken(); // rejects 

Max depth is 64

Oversized return values fail cleanly instead of corrupting the connection

---@ffi
function GetHuge()
    -- a genuinely multi-megabyte structure
    return giant_table
end

await backend.GetHuge(); // rejects 

Bonus fix: plain string/number/boolean returns are now type-correct

---@ffi
function GetCode()
    return "42" -- a real string
end

const code = await backend.GetCode();
typeof code === "string"; // true (used to be 42)

---@class/---@field now resolve to real types instead of unknown

---@class RpcLibraryResult
---@field ok boolean
---@field error string|nil
---@field games EpicGame[]|nil
---@field refreshed_at integer|nil Unix seconds of the last read from Epic

---@ffi
---@return RpcLibraryResult
function GetLibrary(refresh, force, installed)
    return { ok = true, games = {} }
end

---@class EpicGame
---@field id string
---@field name string

Starlight now generates:

interface EpicGame {
    id: string;
    name: string;
}

interface RpcLibraryResult {
    ok: boolean;
    error: string | null;
    games: EpicGame[] | null;
    refreshed_at: number | null;
}

declare const backend: {
    GetLibrary: (refresh: boolean, force: boolean, installed: boolean) => Promise<RpcLibraryResult>;
};

instead of unknown.

[k0d13]

@shdwmtr are those type generations parts included in starlight 1.1.4? cloning the plugin template next branch and running starlight lsp still outputs getPluginStatus: () => Promise<unknown>;