@jakobm/ledlight
v0.6.0
Published
A small, fast Ledger-compatible parser, SQLite store, and reporting library.
Readme
Ledlight
Ledlight is a standalone Ledger-compatible parser, SQLite store, and reporting library.
Install the public package on Node.js 22.14 or later in the Node.js 22 release line:
npm install @jakobm/ledlightFor repository development, install Volta and run
volta setup so its shims are on your PATH. The volta settings in
package.json select Node.js 22.14.0 and npm 11.21.0 automatically in the
repository, new shells, and GitHub Actions.
New Codex worktrees use Volta from PATH when available. Otherwise, environment setup downloads and installs Volta without changing shell profiles, then adds its shims to PATH for the setup shell. It installs dependencies with the pinned toolchain and stops if installation or download fails.
Install dependencies and run the complete verification suite:
npm install
npm testThe maintained source is TypeScript. Run npm run build after editing source to
generate CommonJS files and declarations under dist/ for the tests, CLI, and
npm package. npm test checks the project configuration, builds automatically,
and includes strict type checking and linting. The generated dist/ directory is ignored by Git.
The complete suite requires a Ledger 3 CLI executable named ledger. Set
LEDGER_BIN to another executable path when needed.
The Test GitHub Actions workflow runs on pull requests. Ordinary branch
pushes do not trigger a separate run; pushes to a branch with an open pull
request trigger its checks. Open a draft pull request for CI feedback before
a change is ready for review, or run npm test locally. A new run cancels
older runs for the same pull request.
The full GitHub Actions test job shows total and per-file coverage in its run
summary and uploads a coverage-report artifact. Open its index.html to see
which source lines and branches ran. The same test run also uploads an Allure
report with individual test results and durations. Pushes to main publish
available reports at coverage
and test results on the
existing gh-pages branch, alongside benchmark history in dev/bench/.
PR runs retain available reports even when tests fail. After merge, a separate
workflow publishes the successful PR run’s reports without rerunning tests.
Report artifacts are retained for 14 days. The separate Journal performance
workflow runs benchmarks on pushes to main and manual starts; it records
performance history without enforcing timing thresholds.
Local npm test runs without coverage; use npm run test:coverage and open
coverage/index.html to inspect the report locally.
Run ledlight or ledlight --help to list the available commands. Run
ledlight <command> --help for the options accepted by one command. Run
ledlight version for the package version.
Use the JavaScript API from the package root:
const { openJournal } = require('@jakobm/ledlight');
const journal = openJournal('/path/to/books/main.ledger');The package also includes TypeScript declarations for the public API:
import ledlight = require('@jakobm/ledlight');
const journal = ledlight.openJournal('/path/to/books/main.ledger');
const balances = journal.aggregate({ accounts: ['Assets:*'] });Database operations take the path of the root journal directly. Ledlight stores
its derived SQLite database in the operating system's application cache
directory. The CLI accepts the root journal through --file, a .ledlightrc
file, or stdin. Pipe a journal into any command, or use --file - explicitly.
The JavaScript API continues to take the journal path directly and does not
read stdin. Both the CLI and API honor the cache directory set in the nearest
.ledlightrc or by LEDLIGHT_CACHE_HOME.
Run a complete example without creating a journal file:
ledlight aggregate --accounts 'Assets:*' --include-total <<'LEDGER'
commodity SEK
default
format 1,000.00 SEK
account Assets:Cash
account Equity:Opening
2024-01-01 Opening balance
Assets:Cash 100 SEK
Equity:Opening
LEDGERRead why Ledlight exists for the product's purpose,
strengths, and limits. See the Ledlight documentation for
the supported syntax, reports, and CLI, and the Node.js API
reference for the complete consumer surface. The
architecture diagram shows the repository's module
dependencies. The module system comes from @jakobm/portico.
Supported runtimes, module formats, native platforms, and
compatibility guarantees are defined in the
package support policy. The
Ledger CLI equivalence matrix shows which
commands can be compared and provides a script for checking any journal.
See the benchmark history
for CI performance trends and the benchmark notes for the
fixture and measurement method.
The acquisition-cost allocation guide explains
how Ledlight checks whether recorded sales have a feasible cost basis.
Proposed follow-up work is tracked in the
improvement backlog.
Ledlight is available under the MIT License.
