The official TypeScript / Node.js parser for YINI (by the YINI-lang project) — a human-readable, INI-inspired, indentation-insensitive configuration format with clear nested sections, explicit structure, comments, and predictable parsing.
YINI is intended to emphasize clarity, readability, explicit structure, and predictable parsing, while remaining simple, but not simplistic, and without relying on implicit or indentation-sensitive structure.
Test the package in under one minute.
Install:
npm install yini-parserParse a YINI string:
import YINI from 'yini-parser'
const data = YINI.parse(`
^ Application
name = "demo"
^^ Server
port = 8080
`)
console.log(data)Expected output:
{
Application: {
name: 'demo',
Server: {
port: 8080,
},
},
}npm install yini-parserimport YINI from 'yini-parser'
const config = YINI.parse(`
^ App
name = 'My App'
list = ['web', 'api']
darkMode = true // Yes/On works too
^^ Features
caching = on
object = { logging: true, mode: 'debug' }
`)
console.log(config.App.name) // My App
console.log(config.App.Features.caching) // trueSee the YINI specification and documentation.
- Human-readable — Uses explicit syntax and indentation-independent structure.
- Structured configuration model — Supports sections, nested sections, lists, objects, booleans, and null.
- Predictable parsing — Explicit syntax with clear rules and deterministic parsing behavior.
- TypeScript and Node.js integration — Supports parsing from strings and files.
A basic YINI configuration example, showing a section, a nested section, and comments:
Source: basic.yini
- Demo Apps with usage examples.
- Indentation-independent structure: Spaces and tabs never change meaning, so files can be reformatted without changing structure.
- Explicit nesting: Hierarchy is defined with section markers such as
^,^^, and^^^, rather than by indentation. - Multiple data types: Supports booleans (
true/false,yes/no, etc.), numbers, lists, and inline objects, with explicit string syntax. - Comment support: YINI supports
//,#, block comments (/* ... */), and full-line;comments for documenting configuration directly in the file. - Clear hash comments: Outside string literals,
#always starts a comment; hexadecimal values use0x...orhex:.... - Predictable parsing: Clear rules with optional strict and lenient modes (enforced by the parser) for different use cases.
With npm:
npm install yini-parserWith yarn:
yarn add yini-parserWith pnpm:
pnpm add yini-parserNote: The default export is the main API. Named exports such as parse, parseFile, and parseForTooling are also available from the package entry.
const YINI = require('yini-parser').default;
// If your setup handles default interop differently, try:
// const YINI = require('yini-parser');
// Parse from string.
const config = YINI.parse(`
^ App
title = 'My App Title'
items = 25
isDarkTheme = true
`);
// Parse from file.
const configFromFile = YINI.parseFile('./config.yini');import YINI from 'yini-parser';
// Parse from string.
const config = YINI.parse(`
^ App
title = "My App Title"
items = 25
isDarkTheme = OFF
`);
// Parse from file.
const configFromFile = YINI.parseFile('./config.yini');// JS object
{
App: {
title: "My App Title",
items: 25,
isDarkTheme: false
}
}- Additional YINI examples.
A real-world YINI configuration example, showing sections, nesting, comments, and multiple data types:
Source: config.yini
YINI is intended for configuration files where human readability, explicit structure, and predictable parsing are more important than minimal syntax or maximum flexibility.
Compared with common configuration formats:
- INI: YINI supports clearer nested sections and typed values.
- JSON: YINI supports comments and is easier to edit by hand.
- YAML: YINI does not use indentation to define structure.
- TOML: YINI uses explicit section markers for hierarchy instead of dotted table names.
The same small configuration can be written in several formats:
^ Application
name = 'demo'
environment = 'dev'
^^ Server
host = 'localhost'
ports = [8080, 8081]
^^^ TLS
enabled = true
mode = 'optional'Applicationcontains the top-level application settings.Serveris nested underApplication.TLSis nested underServer.- The section markers
^make the nesting explicit. Indentation is optional and not required for structure. - Strings can use either
'or".
{
"Application": {
"name": "demo",
"environment": "dev",
"Server": {
"host": "localhost",
"ports": [8080, 8081],
"TLS": {
"enabled": true,
"mode": "optional"
}
}
}
}Application:
name: demo
environment: dev
Server:
host: localhost
ports:
- 8080
- 8081
TLS:
enabled: true
mode: optional[Application]
name = "demo"
environment = "dev"
[Application.Server]
host = "localhost"
ports = [8080, 8081]
[Application.Server.TLS]
enabled = true
mode = "optional"Note: YINI may not be the right choice when you need mature ecosystem support, existing schema tooling, or maximum compatibility with infrastructure that already expects JSON, YAML, or TOML.
yini-parser uses TypeScript/JavaScript parser code generated by ANTLR.
The generated parser files are included in the published npm package. Users do not need Java or the ANTLR generator tool to install or use yini-parser.
The package depends on the ANTLR JavaScript/TypeScript runtime used by the generated lexer and parser while parsing.
The ANTLR generator JAR is only needed by maintainers when regenerating parser sources from the grammar, and it is not included in the published npm package.
If you find a problem, please open an issue on GitHub:
When reporting parser behavior, it is helpful to include:
- The YINI input that caused the issue.
- The expected result.
- The actual result or error message.
- The installed
yini-parserversion. - The Node.js version used.
This parser is covered by smoke, integration, and regression tests across lenient, strict, and metadata-enabled modes.
Bug reports, feature requests, discussions, and code contributions are welcome.
GitHub Issues and Discussions are available for feedback and project discussion.
- Project Setup — How to run, test, and build the project, etc.
- Conventions — Project conventions, naming patterns, etc.
This project is licensed under the Apache License 2.0 — see the LICENSE file for details.
In this project on GitHub, the libs directory contains third-party software and each is licensed under its own license which is described in its own license file under the respective directory under libs.
^YINI ≡
YINI is a human-readable configuration format designed for clarity, readability, explicit structure, and predictable parsing.
See the specification for syntax and format details.