https://github.com/gkzhb/lua-types-nvim
TS types for Neovim Lua API with TSToLua
https://github.com/gkzhb/lua-types-nvim
lua neovim typescript typescripttolua
Last synced: about 2 months ago
JSON representation
TS types for Neovim Lua API with TSToLua
- Host: GitHub
- URL: https://github.com/gkzhb/lua-types-nvim
- Owner: gkzhb
- License: mit
- Created: 2022-07-10T13:01:32.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2023-02-08T03:12:51.000Z (over 2 years ago)
- Last Synced: 2025-03-19T06:04:20.743Z (2 months ago)
- Topics: lua, neovim, typescript, typescripttolua
- Language: TypeScript
- Homepage:
- Size: 544 KB
- Stars: 20
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Lua Types for Neovim Lua APIs
[](https://github.com/gkzhb/lua-types-nvim/actions/workflows/npm-publish.yml)
[](https://www.npmjs.com/package/@gkzhb/lua-types-nvim)
[](https://github.com/gkzhb/lua-types-nvim/stargazers)
[](https://github.com/gkzhb/lua-types-nvim/issues)
[](https://github.com/gkzhb/lua-types-nvim/blob/main/LICENSE)
[@gkzhb/lua-types-nvim](https://www.npmjs.com/package/@gkzhb/lua-types-nvim)
provides TypeScript definitions of Neovim(v0.7.2) Lua APIs for
[TypeScriptToLua](https://typescripttolua.github.io/) projects.
Now this project provides types for
* `vim.api`
* `vim.lsp`
* `vim.treesitter`
* `vim.diagnostic`
* `vim.fn`
* `vim.opt`, `vim.go`, `vim.bo`, etc
Inspired by [hrsh7th/deno-nvim-types: The Nvim API type definition for TypeScript](https://github.com/hrsh7th/deno-nvim-types)
and [folke/lua-dev.nvim](https://github.com/folke/lua-dev.nvim).
And thanks for [folke/lua-dev.nvim](https://github.com/folke/lua-dev.nvim)'s
`data` files.
## Usage
1. Add this npm package to your dev dependencies:
```bash
npm install -D @gkzhb/lua-types-nvim
```
2. Add this package in your `tsconfig.json` of TypeScriptToLua:
```json
{
"compilerOptions": {
...
"types": [
...
"@gkzhb/lua-types-nvim"
],
...
}
}
```
## TODO
* [ ] Replace TypeScript types with Lua types.
* [ ] Manually add function parameter types for `vim.fn` which are not provided
in any strctured data.
* [ ] Generate `types/index.d.ts` by code
## Development
TypeScript files in `src/` are node.js code that are executed to generate ts definition
files from Neovim mpack API metadata.
While `.d.ts` files in `types/` are type definitions for Neovim Lua APIs in TypeScriptToLua.
`yarn` scripts:
* Use `yarn` to install dependencies
* `yarn build` to compile TypeScript in `src`
* `yarn dev` to watch for ts file changes and compile to JS
* `yarn parse-nearley` to build parser required to process `vim.fn` documentations
* And `yarn build-dts` to run the compiled js file to generate Neovim API
type definitions.
* `yarn build-api-dts` to process mpack files
* `yarn build-fn-dts` to generate definitions for `vim.fn` from
[`builtin-docs.json`](./data/builtin-docs.json) and [`builtin.txt`](./data/builtin.txt)
* `yarn --silent preview [module]` to output JSON format content of mpack
data, like
```bash
yarn --silent preview lua
```
will output JSON format from `data/lua.mpack`.
* Use `yarn in-one-go` to install dependencies, compile TS and run JS to
generate types in one command.
This project uses TypeScript `factory` to generate ASTs and print them to files.
Refer to [docs.md](./docs.md) for more about development.
### APIs
The structure data about APIs are in `data/` folder.
[`api.mpack`](./data/api.mpack), [`lsp.mpack`](./data/lsp.mpack),
[`lua.mpack`](./data/lua.mpack), [`diagnostic.mpack`](./data/diagnostic.mpack),
[`treesitter.mpack`](./data/treesitter.mpack) and
[`builtin-docs.json`](./data/builtin-docs.json) are from
[folke/lua-dev.nvim](https://github.com/folke/lua-dev.nvim).
Data in these mpack files are the same type `NvimApiFunctions`.
[`builtin-api.mpack`](./data/builtin-api.mpack) is from Neovim command line
```bash
nvim --api-info
```
The data type is `NvimCliApiFunctions`.
[`builtin.txt`](./data/builtin.txt) is from Neovim documentation file in
`$VIMRUNTIME` which contains `vim.fn` summary information in Section 1 Overview.
From this file and [`builtin-docs.json`](./data/builtin-docs.json) I get vim
function name, parameter names, return type and not only brief but also detailed
documentations.
### References
* [factory.createSourceFile doesn't accept JSDoc node (typings issue) · Issue #44151 · microsoft/TypeScript](https://github.com/microsoft/TypeScript/issues/44151)
* [Add capability of transforming and emitting JSDoc comments · Issue #17146 · microsoft/TypeScript](https://github.com/microsoft/TypeScript/issues/17146)
* Thank [TypeScript AST Viewer](https://ts-ast-viewer.com/#) so much for the
useful tool that helps to develop with Typescript AST.
* Also thank [Nearley Parser Playground](https://omrelli.ug/nearley-playground/)
for the great DX with [nearley.js - JS Parsing Toolkit](https://nearley.js.org/).