[Feature Request] Add a strong typed struct/class that cannot assign a new field that is not defined in the struct/class.

[eminor1988]

• Example:

---@struct Student
---@field study_level integer

---@type Student
local new_student = {
    study_level = 0,
    tobacco_level = 1, -- This should be error.
}

• Usage:
  We can do refactoring easier when rename the fields with this feature.

[firas-assaad]

Similar previous discussions:

• Annotation/diagnostic to enforce exact type definition #1602
• Table interface definitions #1652
• Validation and enforcement of @class fields is incomplete/inconsistent #1823

[Mayron]

I'd like to see this too. I'm in favour of struct because it's similar to C#, but exact works fine too. I'm also liking other suggestions for built-in types like Exact<MyClass> instead of more @ styled notation because that might enable support for future features with a more modular approach.

For example, ReadOnly<T> could then also be added to change the behaviour of the wrapped generic type T where T is a collection data type (e.g., a table or list) to tell LuaLS that its read-only, or Callable<MyTable> might be good for declaring that a table has the __call meta-method so you can call it like a function. Who knows 🤷 but it sounds interesting.

[Calandiel]

Would you accept PRs regarding this or is this subject completely off the table?

[sumneko]

Would you accept PRs regarding this or is this subject completely off the table?

I'm glad to accept PRs.

[tmillr]

Really need this feature (for one, it catches typos). It shouldn't be too hard to implement?

Referencing an undefined variable emits an LSP error or warning (even regardless of the fact that it is not a runtime error to do so) and this is a good thing, so why wouldn't the same hold true for table indices?

IIRC, typescript disallows extra keys by default (or maybe it's opt-in behavior to have it that way, I don't remember), and then you can allow additional arbitrary keys on a type by it defining/declaring like this:

type MyObj = {
    [key: string]: any;
    definedKey1: boolean;
    definedKey2: string;
    ...

instead of like this:

type MyObj = {
    definedKey1: boolean;
    definedKey2: string;
    ...

I don't think this is totally necessary however. A special symbol, type constructor, or additional annotation (kinda like @field is its own annotation and goes on its own line) would suffice (whether it's Freeze<> or Exact<> or ---@exact or whatever else).

[GiuseppeIII]

An exact table for the input of functions is also something I would also be very interested in! Initially I was just using params everywhere for function input definitions, but wanted to switch over to using exact dicts as the input to functions utilizing @Class, as I thought it made the code cleaner (especially in places where the arguments in should be 'nested').

One thing I would like to see though if this every makes it in, is the possibility to mark fields on classes as optional using the normal ? syntax. When using the @Class I want to require some fields, allow but not require some other fields, and disallow everything else

[sumneko]

My current idea is

---@class Student
---@exact
---@field study_level integer

or

---@class Student <exact>
---@field study_level integer

Any other good ideas are also welcome.

(Translated by ChatGPT)

[firas-assaad]

I know it'll break existing code and require work to update the definitions everywhere, but would you consider simply changing the existing @class so that it enforces exactness by default? If a user wants to opt out for certain fields, they'll have to manually annotate them as having nil values:

---@field study_level? integer
-- or this, but I prefer the first syntax:
---@field study_level integer?

This is how TypeScript works and while Lua annotations and TypeScript are different, I think enforcing types to be exact by default is a more consistent design that forces the user to think about class fields and whether they should be required or optional.

Of course, I understand the amount of headache involved in updating large codebases and addon libraries, but I thought it's worth mentioning this option if you want to consider it for a future major version.

[lewis6991]

I agree with @firas-assaad . As a compromise this could be enabled by default when only strict is enabled

[sumneko]

I know it'll break existing code and require work to update the definitions everywhere, but would you consider simply changing the existing so that it enforces exactness by default? If a user wants to opt out for certain fields, they'll have to manually annotate them as having nil values:@class

---@field study_level? integer
-- or this, but I prefer the first syntax:
---@field study_level integer?

This is how TypeScript works and while Lua annotations and TypeScript are different, I think enforcing types to be exact by default is a more consistent design that forces the user to think about class fields and whether they should be required or optional.

Of course, I understand the amount of headache involved in updating large codebases and addon libraries, but I thought it's worth mentioning this option if you want to consider it for a future major version.

No, because many users will declare fields using a mixed approach, for example:

---@class MyClass
---@field id integer
local M = Class 'MyClass'

M.showName = 'MyClass'

function M:init()
    self.list = {}
    self.id  = nextID()
end

(Translated by ChatGPT)

[firas-assaad]

No, because many users will declare fields using a mixed approach, for example:

---@class MyClass
---@field id integer
local M = Class 'MyClass'

M.showName = 'MyClass'

function M:init()
    self.list = {}
    self.id  = nextID()
end

(Translated by ChatGPT)

In that case the explicitly set fields are not optional unless they're nil-able, or do you meant that it's technically complex to implement?

Anyway it's just an idea if you want to consider a stricter and more consistent type system instead of adding more special keywords. One thing I notice with the language server is that because users (myself included) ask for a lot of orthogonal features, and there is usually one implementer, the annotations start to get more complex and more inconsistencies can arise.

To be clear, I think you're doing a great job managing all this complexity and carefully reviewing suggestions, but I bring up TypeScript because it's a mature language that went through some similar discussions, and the result is a more consistent and strict model that catches many user errors.

I know that I'm probably not thinking of a lot of the other use cases where my idea won't work. Having any kind of @exact annotation would still be extremely helpful. (I prefer ---@class Student <exact> in your example, assuming there will be new kinds of 'attributes' added to classes in the future)

[sumneko]

I can try adding an option that is enabled by default to enable this feature. If many users give feedback that they don't like this feature, I can downgrade it to default disable and provide new annotations to manually mark it.

(Translated by ChatGPT)

[firas-assaad]

I can try adding an option that is enabled by default to enable this feature. If many users give feedback that they don't like this feature, I can downgrade it to default disable and provide new annotations to manually mark it.

(Translated by ChatGPT)

That's a good compromise. I assume it'll still be in a new major version (4?) because I know this will break most of my existing code 😅

You can also make a separate pinned issue to announce this change and solicit more user feedback before doing it, like you did for some features in the past. That way more users will see it coming, at least.