Skip to content

gkzhb/lua-types-nvim

Repository files navigation

Lua Types for Neovim Lua APIs

GitHub workflow npm version GitHub stars GitHub issues GitHub license

@gkzhb/lua-types-nvim provides TypeScript definitions of Neovim(v0.7.2) Lua APIs for TypeScriptToLua 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 and folke/lua-dev.nvim. And thanks for folke/lua-dev.nvim's data files.

Usage

  1. Add this npm package to your dev dependencies:
npm install -D @gkzhb/lua-types-nvim
  1. Add this package in your tsconfig.json of TypeScriptToLua:
{
  "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 --silent preview [module] to output JSON format content of mpack data, like
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 for more about development.

APIs

The structure data about APIs are in data/ folder.

api.mpack, lsp.mpack, lua.mpack, diagnostic.mpack, treesitter.mpack and builtin-docs.json are from folke/lua-dev.nvim. Data in these mpack files are the same type NvimApiFunctions.

builtin-api.mpack is from Neovim command line

nvim --api-info

The data type is NvimCliApiFunctions.

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 I get vim function name, parameter names, return type and not only brief but also detailed documentations.

References