ini-api

library2.0.2jsnpmunverified

The `ini-api` package provides a robust, class-based API for programmatically parsing, editing, and creating INI configuration files in JavaScript and TypeScript environments. The current stable version is 2.0.2. This library offers distinct classes like `Ini`, `IniSection`, and `IniLine` to represent the structural components of an INI file, allowing for granular manipulation of sections, key-value pairs, and comments. It distinguishes itself by providing a structured object model rather than simple string parsing utilities, enabling developers to interact with INI files using familiar object-oriented patterns. While there isn't a strict release cadence, the project receives updates, with recent significant changes in v2.0.0 (transition to ESM) and v2.0.2 (re-introduction of CJS alongside ESM).

serialization

npm install ini-api

github ↗package ↗

INSTALL

IMPORT

SIG · INI-API

ini-api

serializationjavascriptv2.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Ini

✓ import { Ini } from 'ini-api';

✗ const Ini = require('ini-api').Ini;

The primary class for interacting with INI files. Since v2.0.2, both ESM and CommonJS exports are available. Prior to v2.0.2 (specifically v2.0.0 and v2.0.1), it was ESM-only.

IniSection

✓ import { IniSection } from 'ini-api';

✗ const IniSection = require('ini-api').IniSection;

Represents an individual section within an INI file, including its lines. Part of the named exports for direct manipulation of sections.

lineTypes

✓ import { lineTypes } from 'ini-api';

✗ const lineTypes = require('ini-api').lineTypes;

An object containing constants that define different types of lines found in an INI file (e.g., header, property, comment).

Demonstrates parsing, creating, and modifying INI file content using the `Ini` class, showing how to interact with sections and key-value pairs, and generating string output.

import { Ini, IniSection, IniLine } from 'ini-api'; import fs from 'fs'; import path from 'path'; // Example 1: Creating an empty INI file const emptyIni = new Ini(); console.log('Empty INI:\n', emptyIni.stringify()); // Example 2: Parsing existing INI content const iniText = ` ; This is a comment [General] key1 = value1 key2 = 123 [Database] host = localhost port = 5432 `; const parsedIni = new Ini(iniText); console.log('\nParsed INI:\n', parsedIni.stringify()); // Example 3: Modifying an INI file const generalSection = parsedIni.getSection('General'); if (generalSection) { generalSection.setValue('key3', 'new_value'); } parsedIni.addSection('Security').setValue('admin_email', 'admin@example.com'); console.log('\nModified INI:\n', parsedIni.stringify()); // Example 4: Loading from a file (placeholder for actual file ops) // In a real scenario, you'd read a file: // const configFilePath = path.join(__dirname, 'config.ini'); // const fileContent = fs.readFileSync(configFilePath, 'utf-8'); // const configIni = new Ini(fileContent); // console.log('\nINI from file (simulated):\n', configIni.stringify());

Debug

Known issues

breakingVersion 2.0.0 converted `ini-api` to an ES Module (ESM) only, which was a breaking change for applications built with CommonJS (CJS) that relied on `require()`. This was partially mitigated in v2.0.2.

fix

For projects requiring CommonJS, upgrade to `ini-api@2.0.2` or later, which reintroduces CommonJS exports alongside ESM. Alternatively, refactor your project to use ESM imports (`import ... from 'ini-api';`).

affects: >=2.0.0 <2.0.2

gotchaWhile v2.0.2 reintroduced CommonJS exports, environments with complex module resolution or specific bundler configurations might still encounter issues when attempting to use `require()` if the ESM entry point is prioritized incorrectly.

fix

Ensure your bundler (e.g., Webpack, Rollup) or Node.js environment is configured to correctly resolve CommonJS modules if you intend to use `require()`. For Node.js, explicitly setting `"type": "commonjs"` in your `package.json` for older projects can help, or migrate to ESM imports.

affects: >=2.0.0

gotchaThe `stringify()` method has default options that preserve blank lines and comments. If a more compact or standardized output is required, these defaults need to be overridden.

fix

Explicitly pass options to `stringify()` to control the output. For example, use `ini.stringify({ removeBlankLines: true, removeCommentLines: true })` to get a cleaner INI string without unnecessary whitespace and full comment lines.

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Attempting to use `import` syntax in a CommonJS project (e.g., a script without `"type": "module"` in `package.json`) with `ini-api` versions `>=2.0.0 <2.0.2`.

fix

Upgrade to `ini-api@2.0.2` or later and use `require()` syntax, or convert your project to an ES Module by adding `"type": "module"` to `package.json` and updating your scripts.

TypeError: require is not a function

Attempting to use `require()` in an ES Module context (e.g., a file with `import` statements or within a project with `"type": "module"`) when `ini-api` was ESM-only (`>=2.0.0 <2.0.2`). This can also occur with `v2.0.2+` if an environment incorrectly resolves the CJS export.

fix

For `ini-api@2.0.2+`, ensure your environment correctly resolves the CJS export if you insist on `require()`. Otherwise, refactor to use `import { Ini } from 'ini-api';` and ensure your project is configured for ESM.

(node:xyz) DeprecationWarning: require() of ES Module ... (or similar warnings)

While `ini-api@2.0.2` provides both CJS and ESM exports, mixing `require()` and `import` in complex project setups or specific Node.js environments can sometimes lead to warnings about module interoperability.

fix

Standardize on either `import` (recommended for modern Node.js/browser environments) or `require()` consistently throughout your project. If using `require()`, explicitly ensure your project isn't configured as an ES Module unless necessary.

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/matortheeternal/ini-api ↗

packagehttps://www.npmjs.com/package/ini-api ↗