@kitschpatrol/tokei

Node bindings for Tokei, a fast code counting tool.

Note

This is a fork of faga295/napi-tokei with an updated version of Tokei and a number of additional changes.

An upstream-compatible 1.1.0 version is available on NPM if you just want the updated Tokei dependency.

A 2.0.0+ version with breaking improvements is also available.

A full accounting of the changes is available below.

Overview

Node.js native bindings for Tokei, a fast code statistics tool written in Rust. It counts lines of code, comments, and blanks across 329 programming languages, with support for language filtering, per-file breakdowns, and configurable ignore rules.

Getting started

Dependencies

• Node 18+

Tokei binaries are included for x86_64, aarch64, i686, and armv7.

WebAssembly is not supported.

Installation

Add the library to your project's package.json:

npm install @kitschpatrol/tokei

Invocation

import { tokei } from '@kitschpatrol/tokei'

const results = await tokei()

// Returns:
// [
//   { language: 'JavaScript', files: 2, lines: 610, code: 577, comments: 12, blanks: 21 },
//   { language: 'JSON', files: 6, lines: 156, code: 156, comments: 0, blanks: 0 },
//   { language: 'Markdown', files: 1, lines: 81, code: 0, comments: 57, blanks: 24 },
//   { language: 'Rust', files: 3, lines: 135, code: 126, comments: 0, blanks: 9 },
//   { language: 'TOML', files: 2, lines: 25, code: 20, comments: 0, blanks: 5 },
//   { language: 'TypeScript', files: 4, lines: 596, code: 502, comments: 68, blanks: 26 },
//   { language: 'YAML', files: 1, lines: 2869, code: 2230, comments: 0, blanks: 639 }
// ]

Usage

The library exposes tokei(options?) and tokeiSync(options?) functions with options similar to those provided by the Tokei's get_statistics method and the Tokei CLI tool.

API

tokei(options?): Promise<LanguageInfo[]>

Count lines of code, comments, and blanks across files and languages. Runs on a background thread and returns a promise, so it doesn't block the Node.js event loop.

tokeiSync(options?): LanguageInfo[]

Synchronous version of tokei. Blocks the event loop until the analysis is complete. Useful for scripts, CLI tools, or cases where blocking is acceptable.

TokeiOptions

All fields are optional.

Field	Type	Default	Description
include	string[]	["."]	Paths to include in the analysis. Defaults to the current working directory.
exclude	string[]		Paths to exclude from the analysis. Tokei respects .gitignore and similar files by default.
languages	Language[]		Filter results to only these languages. Uses Tokei display names (e.g. "Rust", "ASP.NET"). Invalid names are silently ignored.
hidden	boolean	false	Include hidden files and directories.
noIgnore	boolean	false	Don't respect any ignore files. Implies noIgnoreParent, noIgnoreDot, and noIgnoreVcs.
noIgnoreParent	boolean	false	Don't respect ignore files in parent directories.
noIgnoreDot	boolean	false	Don't respect .ignore and .tokeignore files.
noIgnoreVcs	boolean	false	Don't respect VCS ignore files (.gitignore, .hgignore, etc.).
treatDocStringsAsComments	boolean	false	Count doc strings (e.g. Python """...""", Rust ///) as comments instead of code.
files	boolean	false	Include per-file statistics in the reports field of each result.

LanguageInfo

Aggregated code statistics for a single programming language.

Field	Type	Description
language	Language	The language name, e.g. "Rust", "TypeScript", "ASP.NET".
files	number	Number of files detected for this language.
lines	number	Total number of lines (code + comments + blanks).
code	number	Lines of code (excluding comments and blanks).
comments	number	Lines of comments.
blanks	number	Blank lines.
reports	Report[]?	Per-file statistics. Only populated when files is true in options.

Report

Code statistics for a single file. Only included when files: true is set.

Field	Type	Description
name	string	The file path.
lines	number	Total number of lines (code + comments + blanks).
code	number	Lines of code (excluding comments and blanks).
comments	number	Lines of comments.
blanks	number	Blank lines.

Language

A TypeScript string literal union of all 329 supported language names, providing autocomplete and type safety for the languages option. See the full list in the type definitions.

Examples

import { tokei, tokeiSync } from '@kitschpatrol/tokei'

// Basic async usage
const results = await tokei()

// Basic sync usage
const resultsSync = tokeiSync()

// Filter by language
const tsOnly = await tokei({
  exclude: ['secret_folder'],
  languages: ['TypeScript'],
})

// With per-file reports and config options
const detailed = await tokei({
  include: ['.'],
  exclude: ['secret_folder'],
  languages: ['TypeScript', 'Rust'],
  files: true,
  hidden: true,
  treatDocStringsAsComments: true,
})

Changes

Modifications from upstream include the following:

1.1.0+

• Tokei 14
  Adds 'files' count to returned object. Other bug fixes and improvements.

• Modernized project template
  Based on latest napi-rs/package-template-pnpm

• Integration tests

2.0.0+

• tokei() is now async and returns a Promise
  Breaking
  The tokei() function now runs on a background thread and returns Promise<LanguageInfo[]> instead of LanguageInfo[]. A synchronous tokeiSync() function is also available. To migrate, either await the result of tokei(), or switch to tokeiSync().

• Language names use Tokei display names
  Breaking
  Ensures consistency across input and output.

• Invalid language names are silently ignored
  Breaking
  Instead of falling back to Text.

• CodeStatus type removed.
  Breaking
  The Report type now directly contains lines, code, comments, and blanks fields.

• lang field renamed to language
  Breaking

• Additional configuration options
  hidden, noIgnore, noIgnoreParent, noIgnoreDot, noIgnoreVcs, and treatDocStringsAsComments are now exposed, matching Tokei's Config struct.

• Per-file statistics
  Set files: true to get a reports array on each LanguageInfo with per-file breakdowns. (Equivalent to the Tokei CLI --files flag.)

• Language type
  A TypeScript string literal union of all 329 supported language names, providing autocomplete and type safety for the languages option.

• JSDoc comments
  Provide documentation-on-hover for all exported types and fields.

Maintainers

@kitschpatrol

Acknowledgments

Erin Power (@XAMPPRocky) and contributors develop the Tokei library and CLI.

Liu Zhaochen (@faga295) developed the fork on which this repo is based.

The napi-rs project makes bridging Rust and Node much more tractable.

Contributing

Issues and pull requests are welcome.

License

MIT © Eric Mika

The above license applies to changes in this fork, the MIT-licensed upstream and template projects are cited in license.txt.