Annotating events and callbacks

[swarn]

I'm creating definition files for the Elder Scrolls Online API. It defines global values for event IDs and a registration function. What's possible and what are best practices for annotating a callback system? I've got a sort of minimal working example below, which includes two specific questions:

-- The API defines global event IDs
EVENT_A = 1
EVENT_B = 2

-- I tried to create an enum of events like this:
---@alias EventId
---| `EVENT_A`
---| `EVENT_B`

-- I annotated the callback registration like so:
---@param eventId EventId
---@param callback function
function RegisterForEvent(eventId, callback) end

-- The event A callback only passes the event id.
RegisterForEvent(
  EVENT_A,
  function(eventId) print("event A happened with eventId", eventId) end
)

-- The event B callback also passes a number
RegisterForEvent(
  EVENT_B,
  function(eventId, bNumber)
    print(string.format("B with eventId %d and number %f", eventId, bNumber))
  end
)

-- Question 1: Can type-checking identify that 3 is not a valid eventId? It's not
-- flagging this one.
RegisterForEvent(3, function() end)

-- Question 2: Is there a way that type-checking can identify that the callback has
-- the wrong signature?
RegisterForEvent(EVENT_A, function(a, b, c) end)

[swarn]

It seems like I made up a capability in the example above that doesn't work. This doesn't work:

EVENT_A = 1
EVENT_B = 2

---@alias EventId
---| `EVENT_A`
---| `EVENT_B`

The EventId type becomes effectively any. But this does work:

EVENT_A = 1
EVENT_B = 2

---@alias EventId
---| 1
---| 2

[swarn]

Maybe this is related to #2721

[tomlau10]

• For Q1, in order to identity that 3 is not a valid eventId, you have to specify the accepted param type of eventId to be a union of 1 and 2 only.
  As you have experimented, the backtick literal type is only for auto completion hint, if you have an alias which are all these backtick literal, the alias type is still any, and that's why when changed to the following:

---@alias EventId
---| 1
---| 2

the type checking of eventId starts to work.

• For Q2, there is an @overload annotation, and you can overload a function signature based on the param value. LuaLS will try to type narrow it to the correct signature, but as far as I know this functionality is not that perfect. Still we can give a try.

---

Just using your example above, you can have something like this:

EVENT_A = 1
EVENT_B = 2

---@alias EventId
---| 1
---| 2

---@param eventId EventId
---@param callback function
---@overload fun(eventId: 1, callback: fun(eventId))
---@overload fun(eventId: 2, callback: fun(eventId, bNumber: number))
function RegisterForEvent(eventId, callback) end

-- both `RegisterForEvent` calls in your 2 questions will throw error now
-- first one with `param-type-mismatch` warning
-- the other one with `redundant-parameter` warning

---

But as you can see, the above annotation is not that great because of the direct writing of the enum values, instead of writing enum names. Now I can come up with the following improvement: to alias each enum value with its name

EVENT_A = 1 ---@alias EventId.EVENT_A 1
EVENT_B = 2 ---@alias EventId.EVENT_B 2

---@alias EventId
---| EventId.EVENT_A
---| EventId.EVENT_B

---@param eventId EventId
---@param callback function
---@overload fun(eventId: EventId.EVENT_A, callback: fun(eventId))
---@overload fun(eventId: EventId.EVENT_B, callback: fun(eventId, bNumber: number))
function RegisterForEvent(eventId, callback) end

Although for each new enum, you have to write it 3 times:

• One is for global definition
• One is for the alias EventId.* name
• One is to add this new enum value into the union alias type EventId

But hey, now you can use the type names when writing function overload definitions 🎉
I don't know if there are any other simpler ways to achieve your goal.
Hope this helps and maybe it can inspire you or others to give some better suggestions 😄

[swarn]

Wow, this is great! Many thanks. I've been messing around with generics trying to get something working, with not much success.

The little bit of verbosity is fine; I'll be generating this with a script from their documentation, anyway. I don't know how you'd simplify it; you need to 1) introduce the global values to the type system, 2) identify them as an enum, and 3) write the per-event signatures somewhere.

Per the advice of the wiki, for a definition file I split the overload into redundant function definitions. That gives me a definition file that looks like this:

---@meta

EVENT_A = 1 ---@alias EventId.EVENT_A 1
EVENT_B = 2 ---@alias EventId.EVENT_B 2

---@alias EventId
---| EventId.EVENT_A
---| EventId.EVENT_B

---@param eventId EventId.EVENT_A
---@param callback fun(eventId: EventId)
function RegisterForEvent(eventId, callback) end

---@param eventId EventId.EVENT_B
---@param callback fun(eventId: EventId, bNumber: number)
function RegisterForEvent(eventId, callback) end

and this bit of test code

---@diagnostic disable:unused-local

-- Correct signatures
RegisterForEvent(EVENT_A, function(eventId) end)
RegisterForEvent(EVENT_B, function(eventId, bNumber) end)

-- Correctly flags `param-type-mistmatch` on first argument.
RegisterForEvent(3, function() end)
RegisterForEvent(nil, function() end)

-- Correctly flags `redundant-parameter` on second argument.
RegisterForEvent(EVENT_A, function(a, b) end)

-- Correctly infers the types of a and b here
RegisterForEvent(EVENT_B, function(a, b)
  print(a) -- a is type EventId
  print(b) -- b is type number
end)

---@param a boolean
---@param b boolean
local function f(a, b) end

-- No warning here.
RegisterForEvent(EVENT_A, f)

It's interesting that when using an anonymous function, it correctly infers the argument types from the RegisterForEvent overload, but for the named function, it doesn't identify the signature mismatch (both number and types of arguments). I'm asking for a lot, I know :). This is possibly related to #1456 , as also mentioned in the wiki..

[tomlau10]

but for the named function, it doesn't identify the signature mismatch

Yeah also I found this recently. I think it's not related to the overload functionality, but the type tracking when passing a named function variable in general. I've opened an similar issue here #2695, it seems that the type tracking of function will just stop if you use a named function 😕
=> it will not pass along the inferred variable type to your named function.

---

For named function check, what I can come up with is to alias the callback function type. But this requires you to also write the ---@type when declaring the actual named callback function, so this may not suitable for your case.
(I guess you are just writing meta definition files only, but not modifying others' scripts?)

• alias the callback function type

---@alias EventCb.EVENT_A fun(eventId: EventId)
---@param eventId EventId.EVENT_A
---@param callback EventCb.EVENT_A
function RegisterForEvent(eventId, callback) end

---@alias EventCb.EVENT_B fun(eventId: EventId, bNumber: number)
---@param eventId EventId.EVENT_B
---@param callback EventCb.EVENT_B
function RegisterForEvent(eventId, callback) end

• then in the actual script that calls it

---@type EventCb.EVENT_A
local function f(a, b) end  ---<<< this will throw warning now

-- but still no warning here
RegisterForEvent(EVENT_A, f)

[swarn]

Ah, I see. You're right, I'm just writing definition files, so this doesn't quite get me there. But, this is still miles better than what I was coming up with. I'll mark the earlier post as the answer, and subscribe to #2695 to keep an eye on things. Thanks!