@notfounnd/ini-parser

A professional INI file parser for Node.js with CLI support. Parse INI configuration files into structured JavaScript objects with support for sections, multi-line values, comments and global keys.

✨ TL;DR

Library Usage (JavaScript):

const { parse } = require('@notfounnd/ini-parser');

const content = `
# Database configuration
[database]
host=localhost
port=5432
`;

const result = parse(content);
console.log(result); // { database: { host: ['localhost'], port: ['5432'] } }

CLI Usage:

ini-parser config.ini                    # Parse and output JSON
ini-parser config.ini --output data.json # Save to file
ini-parser config.ini --check            # Validate file

🚀 Features

📦 Library & CLI: Use as a Node.js module or command-line tool
🔧 INI Standard Support: Sections, key-value pairs, comments (# and ;)
📝 Multi-line Values: Indented continuation lines
🌍 Global Keys: Keys outside of sections
🎯 Flexible Output: Simplified or metadata format
✅ Validation: File checking with statistics
🎨 Colored Output: User-friendly CLI messages
⚡ Zero Config: Works out of the box
🧪 Well Tested: Comprehensive test suite

📦 Installation

As a Library

npm install @notfounnd/ini-parser

As a CLI Tool

npm install -g @notfounnd/ini-parser

🏁 Quick Start

As a Library

const { parse } = require('@notfounnd/ini-parser');

// Example INI content
const content = `
# Database configuration
[database]
host=localhost
port=5432
name=myapp

[server]
port=3000
workers=4 8 16 32
`;

// Parse with simplified format (default)
const result = parse(content);
console.log(result);
// Output:
// {
//   database: {
//     host: ['localhost'],
//     port: ['5432'],
//     name: ['myapp']
//   },
//   server: {
//     port: ['3000'],
//     workers: ['4', '8', '16', '32']
//   }
// }

// Parse with metadata format
const metaResult = parse(content, { meta: true });
console.log(metaResult);
// Output includes type information:
// {
//   database: {
//     type: 'section',
//     content: {
//       host: { type: 'configuration', content: ['localhost'] },
//       port: { type: 'configuration', content: ['5432'] },
//       name: { type: 'configuration', content: ['myapp'] }
//     }
//   },
//   ...
// }

As a CLI

# Parse INI file and output to stdout
ini-parser config.ini

# Save output to JSON file
ini-parser config.ini --output result.json

# Parse with metadata format
ini-parser config.ini --meta

# Validate file and show statistics
ini-parser config.ini --check

# Save to file without stdout (quiet mode)
ini-parser config.ini --output result.json --quiet

# Show version
ini-parser --version

# Show help
ini-parser --help

📚 Documentation

API Reference - Detailed library API documentation
CLI Reference - Complete CLI usage guide
Parser Rules - INI parser behavior and rules

🔌 API Overview

`parse(content, options)`

Parses INI file content into a structured JavaScript object.

Parameters:

content (string): The INI file content as a string
options (object, optional):
- meta (boolean): If true, returns metadata format with type information; if false, returns simplified format (default: false)

Returns: object - Parsed INI data

Output Formats:

Simplified Format (default): Clean object structure with arrays of values

{
  section: {
    key: ['value1', 'value2']
  }
}

Metadata Format (meta: true): Includes type information for advanced use cases

{
  section: {
    type: 'section',
    content: {
      key: {
        type: 'configuration',
        content: ['value1', 'value2']
      }
    }
  }
}

Supported Features:

✅ Sections: [section_name]
✅ Key-value pairs: key=value
✅ Multi-line values (indented continuation)
✅ Global keys (outside of sections)
✅ Comments: # and ; at line start
✅ Inline comments: key=value # comment
✅ Automatic value splitting by spaces
✅ Empty value handling

💻 CLI Overview

Syntax

ini-parser <file> [options]

Arguments

<file>: Path to INI file (required)

Options

Flag	Alias	Description
`--output <file>`	`-o`	Save output to JSON file
`--meta`	-	Return metadata format with type information
`--quiet`	`-q`	Suppress stdout output when saving to file
`--check`	-	Check INI file and display statistics without full output
`--version`	`-v`	Output the current version
`--help`	`-h`	Display help information

Exit Codes

0: Success
1: File error (not found, not readable, parse error)
2: Argument error (invalid arguments, missing file)

Examples

# Basic parsing
ini-parser config.ini

# Save to file
ini-parser config.ini -o output.json

# Validate file
ini-parser config.ini --check
# Output:
# [ SUCCESS ] File found: config.ini
# [ SUCCESS ] File readable: yes
# [ SUCCESS ] Parsed successfully: 3 sections, 12 keys

# Quiet mode (save without stdout)
ini-parser config.ini --output data.json --quiet

# Metadata format
ini-parser config.ini --meta --output meta.json

🧪 Examples

Global Keys

# Global configuration
debug=true
log_level=info

[database]
host=localhost

Parsed result:

{
  debug: ['true'],
  log_level: ['info'],
  database: {
    host: ['localhost']
  }
}

Multi-line Values

[paths]
include=
  /usr/local/bin
  /usr/bin
  /bin

Parsed result:

{
  paths: {
    include: ['/usr/local/bin', '/usr/bin', '/bin']
  }
}

Space-separated Values

[server]
ports=8080 8081 8082

Parsed result:

{
  server: {
    ports: ['8080', '8081', '8082']
  }
}

Comments

# This is a comment
; This is also a comment

[section]
key=value # inline comment

Parsed result:

{
  section: {
    key: ['value']
  }
}

🛠️ Development

Prerequisites

Node.js >= 18.0.0
npm >= 9.0.0

Setup

# Clone repository
git clone https://github.com/notfounnd/ini-parser.git
cd ini-parser

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run linter
npm run lint:check

# Format code
npm run format

Project Structure

ini-parser/
├── bin/               # CLI executable
├── src/
│   ├── lib/          # Library code (parser.js)
│   └── cli/          # CLI implementation
├── test/             # Test suites
├── docs/             # Documentation
└── package.json

CI/CD & Workflows

This project uses GitHub Actions for continuous integration and deployment with a Trunk-Based Development strategy.

Workflow Triggers

Feature CI (ci-feature.yml): Runs on push to any branch except master
- Tests on Node.js 18.x, 20.x, 22.x
- Runs ESLint, Prettier, and Jest tests
Master CI/CD (ci-master.yml): Runs on push to master (via PR merge)
- Tests on Node.js 18.x, 20.x, 22.x
- Builds production artifact (.tgz) with Node.js 22.x
- Runs E2E tests with installed package (8 tests)
Release (release.yml): Manual trigger only (workflow_dispatch)
- Calculates version from conventional commits
- Generates/updates CHANGELOG.md
- Publishes to NPM
- Creates GitHub Release

Branch Protection Rules

The master branch is protected with the following rules:

✅ Squash merge only (maintains linear history)
✅ Pull request required (no direct pushes)
✅ Status checks required (CI must pass)
✅ Branches must be up to date
✅ Conversation resolution required
✅ Rules enforced for administrators

Release Process

This project follows Trunk-Based Development with manual releases:

Development: Work on feature branches
Pull Request: Squash merge to master (triggers Master CI/CD)
Release: Manual workflow trigger with dry-run option
Automation: release-it handles versioning, changelog, and publishing

Release Strategy:

Version calculated from conventional commits (feat → MINOR, fix → PATCH)
Changelog auto-generated from commit history
Package built and tested with E2E validation before release
GitHub Release created with changelog notes

🤝 Contributing

Contributions are welcome! This project is actively maintained and we appreciate your help.

How to contribute:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Guidelines:

Follow existing code style (ESLint + Prettier configured)
Add tests for new features
Update documentation as needed
Ensure all tests pass (npm test)

For detailed contribution guidelines, see CONTRIBUTING.md.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

Repository: github.com/notfounnd/ini-parser
Issues: github.com/notfounnd/ini-parser/issues
Changelog: CHANGELOG.md
Author: Júnior Sbrissa

Made with ❤️ by Júnior Sbrissa | Errør 404 | NotFounnd

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.agents		.agents
.github		.github
bin		bin
docs		docs
src		src
test		test
.editorconfig		.editorconfig
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.release-it.json		.release-it.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json

License

notfounnd/ini-parser

Folders and files

Latest commit

History

Repository files navigation

@notfounnd/ini-parser

✨ TL;DR

🚀 Features

📦 Installation

As a Library

As a CLI Tool

🏁 Quick Start

As a Library

As a CLI

📚 Documentation

🔌 API Overview

parse(content, options)

💻 CLI Overview

Syntax

Arguments

Options

Exit Codes

Examples

🧪 Examples

Global Keys

Multi-line Values

Space-separated Values

Comments

🛠️ Development

Prerequisites

Setup

Project Structure

CI/CD & Workflows

Workflow Triggers

Branch Protection Rules

Release Process

🤝 Contributing

📄 License

🔗 Links

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Contributors 2

Uh oh!

Languages

`parse(content, options)`