The types say: repl: string | Record<string, string> | ((...matches: string[]) => string),, whereas the above docstring says: "otherwise, if it is false or nil, then there is no replacement" - therefore, this should be an optional string, as it may be nil.

Furthermore, I believe a () capture group will return an index, so the matches aren't even necessarily a string[], but may be either number or string. gmatch etc might have similar issues.

You should maybe declare a match type which may be either a number or a string.