ini

What is ini?

The ini npm package is used for parsing .ini files and converting objects to .ini format. It provides a simple interface for working with INI configuration files, which are often used for storing settings in a structured yet readable format. This package allows for easy reading, writing, and manipulation of INI files.

What are ini's main functionalities?

Parse INI string

This feature allows you to parse a string in INI format and convert it into a JavaScript object. The example demonstrates parsing a simple INI formatted string.

"const ini = require('ini');\nconst config = ini.parse('[section]\na=1\nb=2');\nconsole.log(config); // { section: { a: '1', b: '2' } }"

Stringify an object to INI format

This feature converts a JavaScript object into a string in INI format. The example shows how to convert an object with nested properties into an INI formatted string.

"const ini = require('ini');\nconst obj = { section: { a: '1', b: '2' } };\nconst str = ini.stringify(obj);\nconsole.log(str); // '[section]\na=1\nb=2'"

Other packages similar to ini

dotenv

dotenv is a package that loads environment variables from a .env file into process.env. While it serves a different purpose by focusing on environment variables, it shares the concept of managing configuration through a file. Unlike ini, dotenv does not support sections or nested properties.

rc

rc is a configuration package that reads properties from multiple sources, including INI files, environment variables, and command-line arguments. It offers more flexibility in configuration management compared to ini by aggregating settings from various sources, but it might be more complex to use for simple INI file parsing and writing.

config

config is a more comprehensive configuration management solution that supports multiple file formats, including JSON, YAML, and JavaScript. It is designed for organizing hierarchical configurations for app deployments. While it provides more features and supports more formats than ini, it might be overkill for simple INI file tasks.

README

An INI format parser & serializer.

Note

• Sections are treated as nested objects.

• Section-less items are treated as globals.

Usage

Consider an INI file such as the following:

; This comment is being ignored
scope = global

[database]
user = dbuser
password = dbpassword
database = use_this_database

[paths.default]
datadir = /var/lib/data
array[] = first value
array[] = second value
array[] = third value

You can read, modify and write it like so:

import { writeFile , readFile } from 'node:fs/promises'
import { stringify , parse } from 'ini'

//  Read INI file as text

let text = await readFile(`./Original.ini`,{
    encoding : 'utf-8'
})

//  Parse text data to object

const config = parse(text)

//  Modify data object

config.scope = 'local'
config.database.database = 'use_another_database'
config.paths.default.tmpdir = '/tmp'
delete config.paths.default.datadir
config.paths.default.array.push('fourth value')

//  Stringify data object

text = stringify(config,{ 
    section : 'section' 
})

//  Write INI file as text

await writeFile(`./Modified.ini`,text)

The written file will contain the following:

[section]
scope=local
[section.database]
user=dbuser
password=dbpassword
database=use_another_database
[section.paths.default]
tmpdir=/tmp
array[]=first value
array[]=second value
array[]=third value
array[]=fourth value

API

Parse

Attempts to turn the given INI string into a nested data object.

// You can also use `decode`
const object = parse(`<INI Text>`) 

Stringify

Encodes the given data object as an INI formatted string.

// You can also use `encode`
stringify(object,{

    /**
     *  Whether to insert spaces before & after `=`
     * 
     *  Disabled by default to have better 
     *  compatibility with old picky parsers.
     */

    whitespace : false ,

    /**
     *  Whether to align the `=` character for each section.
     *  -> Also enables the `whitespace` option
     */

    align : false ,

    /**
     *  Identifier to use for global items 
     *  and to prepend to all other sections.
     */

    section ,

    /**
     *  Whether to sort all sections & their keys alphabetically.
     */

    sort : false ,

    /**
     *  Whether to insert a newline after each section header.
     * 
     *  The TOSHIBA & FlashAir parser require this format. 
     */

    newline : false ,

    /**
     *  Which platforms line-endings should be used.
     * 
     *  win32 -> CR+LF
     *  other -> LF
     * 
     *  Default is the current platform
     */

    platform ,

    /**
     *  Whether to append `[]` to array keys.
     * 
     *  Some parsers treat duplicate names by themselves as arrays
     */

    bracketedArray : true

})

For backwards compatibility any string passed as the
options parameter is treated as the section option.

stringify(object,'section')

Un / Escape

Turn the given string into a safe to
use key or value in your INI file.

safe(`"unsafe string"`) // -> \"unsafe string\"

Or reverse the process with:

unsafe(`\\"safe string\\"`) // -> "safe string"

Changelog

5.0.0 (2024-09-03)

⚠️ BREAKING CHANGES

• ini now supports node ^18.17.0 || >=20.5.0

Bug Fixes

• 3eca645 #279 align to npm 10 node engine range (@hashtagchris)

Chores

• c89e209 #279 run template-oss-apply (@hashtagchris)
• fc44750 #276 bump @npmcli/eslint-config from 4.0.5 to 5.0.0 (@dependabot[bot])
• 21c20bb #277 postinstall for dependabot template-oss PR (@hashtagchris)
• 44b3b50 #277 bump @npmcli/template-oss from 4.23.1 to 4.23.3 (@dependabot[bot])