or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-ini

An INI encoder/decoder for Node.js applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ini@4.1.x

To install, run

npx @tessl/cli install tessl/npm-ini@4.1.0

index.mddocs/

INI

An INI encoder/decoder for Node.js applications. Provides comprehensive INI file format parsing and serialization with support for nested sections, arrays, and various formatting options.

Package Information

  • Package Name: ini
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install ini

Core Imports

const { parse, stringify, encode, decode, safe, unsafe } = require("ini");

For ES modules:

import { parse, stringify, encode, decode, safe, unsafe } from "ini";

Basic Usage

const { parse, stringify } = require("ini");

// Parse INI text to object
const config = parse(`
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
`);

// Modify the object
config.scope = 'local';
config.database.database = 'use_another_database';
config.paths.default.tmpdir = '/tmp';

// Convert back to INI text
const iniText = stringify(config, { section: 'section' });

Capabilities

INI Parsing

Parse INI format strings into JavaScript objects with support for sections, arrays, and type conversion.

/**
 * Parse INI format string into nested JavaScript object (alias for decode)
 * @param {string} str - INI formatted text
 * @param {object} [opt] - Parsing options
 * @param {boolean} [opt.bracketedArray=true] - Whether to treat keys ending with [] as arrays
 * @returns {object} Parsed object with nested sections
 */
function parse(str, opt);

/**
 * Parse INI format string into nested JavaScript object
 * @param {string} str - INI formatted text  
 * @param {object} [opt] - Parsing options
 * @param {boolean} [opt.bracketedArray=true] - Whether to treat keys ending with [] as arrays
 * @returns {object} Parsed object with nested sections
 */
function decode(str, opt);

Usage Examples:

const { parse } = require("ini");

// Basic parsing
const config = parse(`
name = value
number = 42
bool = true
`);
// Result: { name: 'value', number: '42', bool: true }

// Section parsing
const configWithSections = parse(`
global = setting

[section1]
key = value

[section2.subsection]
nested = deep
`);
// Result: { 
//   global: 'setting',
//   section1: { key: 'value' },
//   section2: { subsection: { nested: 'deep' } }
// }

// Array parsing with brackets
const configWithArrays = parse(`
[database]
hosts[] = server1
hosts[] = server2
hosts[] = server3
`);
// Result: { database: { hosts: ['server1', 'server2', 'server3'] } }

// Array parsing without brackets (duplicate keys)
const configDuplicateKeys = parse(`
[database]
host = server1
host = server2
host = server3
`, { bracketedArray: false });
// Result: { database: { host: ['server1', 'server2', 'server3'] } }

// Comment parsing
const configWithComments = parse(`
; This is a comment
# This is also a comment
name = value
; Comments are ignored

[section]
key = value  ; inline comments work too
`);
// Result: { name: 'value', section: { key: 'value' } }

INI Encoding

Convert JavaScript objects to INI format strings with comprehensive formatting options.

/**
 * Convert JavaScript object to INI formatted string (alias for encode)
 * @param {object} obj - JavaScript object to encode
 * @param {object|string} [opt] - Encoding options object or section name string
 * @param {string} [opt.section] - Section name to prepend to all keys
 * @param {boolean} [opt.align=false] - Align = characters (automatically enables whitespace)
 * @param {boolean} [opt.newline=false] - Add newline after section headers
 * @param {boolean} [opt.sort=false] - Sort sections and keys alphabetically
 * @param {boolean} [opt.whitespace=false] - Add spaces around = characters
 * @param {string} [opt.platform=process.platform] - Platform for line endings ('win32' for CRLF, others for LF, auto-detected)
 * @param {boolean} [opt.bracketedArray=true] - Append [] to array keys
 * @returns {string} INI formatted string
 */
function stringify(obj, opt);

/**
 * Convert JavaScript object to INI formatted string
 * @param {object} obj - JavaScript object to encode
 * @param {object|string} [opt] - Encoding options object or section name string
 * @param {string} [opt.section] - Section name to prepend to all keys
 * @param {boolean} [opt.align=false] - Align = characters (automatically enables whitespace)
 * @param {boolean} [opt.newline=false] - Add newline after section headers
 * @param {boolean} [opt.sort=false] - Sort sections and keys alphabetically
 * @param {boolean} [opt.whitespace=false] - Add spaces around = characters
 * @param {string} [opt.platform=process.platform] - Platform for line endings ('win32' for CRLF, others for LF, auto-detected)
 * @param {boolean} [opt.bracketedArray=true] - Append [] to array keys
 * @returns {string} INI formatted string
 */
function encode(obj, opt);

Usage Examples:

const { stringify } = require("ini");

// Basic encoding
const obj = {
  global: 'setting',
  database: {
    host: 'localhost',
    port: 5432
  }
};
const basic = stringify(obj);
// Result:
// global=setting
// [database]
// host=localhost
// port=5432

// Encoding with section prefix
const withSection = stringify(obj, { section: 'app' });
// Result:
// [app]
// global=setting
// [app.database]
// host=localhost
// port=5432

// Encoding with formatting options
const formatted = stringify(obj, {
  whitespace: true,
  align: true,
  sort: true
});
// Result (with aligned = signs and spaces):
// global = setting
// [database]
// host   = localhost
// port   = 5432

// Encoding arrays
const objWithArrays = {
  servers: ['web1', 'web2', 'web3']
};
const withArrays = stringify(objWithArrays);
// Result:
// servers[]=web1
// servers[]=web2
// servers[]=web3

// Encoding arrays without brackets
const withoutBrackets = stringify(objWithArrays, { bracketedArray: false });
// Result:
// servers=web1
// servers=web2
// servers=web3

// Cross-platform line endings
const win32Format = stringify(obj, { platform: 'win32' });
// Uses CRLF line endings instead of LF

// String parameter shorthand (equivalent to { section: 'mysection' })
const withSection = stringify(obj, 'mysection');

String Parameter Shorthand:

For convenience, you can pass a string as the second parameter instead of an options object. This string will be used as the section name:

// These are equivalent:
stringify(object, 'section')
stringify(object, { section: 'section' })

String Escaping

Utilities for safely escaping and unescaping strings in INI format.

/**
 * Escape unsafe characters in strings for INI format
 * @param {any} val - Value to make safe for INI format
 * @returns {string} String with escaped characters
 */
function safe(val);

/**
 * Unescape INI format strings back to original values
 * @param {string} val - INI formatted value to unescape
 * @returns {string} Unescaped string value
 */
function unsafe(val);

Usage Examples:

const { safe, unsafe } = require("ini");

// Escaping unsafe strings
const escaped = safe('"quoted string"');
// Result: "\"quoted string\""

const escapedSpecial = safe('value with = and \n newline');
// Result: "value with = and \\n newline"

const escapedComments = safe('value ; with comment');
// Result: "value \\; with comment"

// Unescaping strings
const unescaped = unsafe('\\"safe string\\"');
// Result: "safe string"

const unescapedSpecial = unsafe('value \\; with \\# comment');
// Result: "value ; with # comment"

Key Features

Section Support

  • Nested objects become INI sections [section.subsection]
  • Dot-separated section names with escaping support
  • Automatic section hierarchy handling

Array Handling

  • Arrays represented with bracketed notation key[] = value by default
  • Alternative duplicate key format key = value1, key = value2
  • Configurable via bracketedArray option

Type Conversion

  • Automatic parsing of boolean values (strings 'true' and 'false' become boolean primitives)
  • Automatic parsing of null values (string 'null' becomes null)
  • String values preserved as strings
  • Numeric strings remain as strings (no automatic number conversion)
  • Only exact string matches 'true', 'false', and 'null' are converted

Comment Support

  • Lines starting with ; or # are treated as comments and ignored during parsing
  • Empty lines and whitespace-only lines are also ignored
  • Comments can appear anywhere in the INI file

Security Features

  • Protection against __proto__ pollution in parsing and encoding (keys named __proto__ are filtered out)
  • Safe handling of escaped characters in string values
  • Secure object creation with Object.create(null) to avoid prototype pollution

Cross-Platform Support

  • Configurable line endings (CRLF on Windows, LF elsewhere)
  • Platform detection via process.platform
  • Browser compatibility with fallback handling

Formatting Options

  • Configurable whitespace around = characters
  • Optional alignment of = characters within sections
  • Optional sorting of sections and keys
  • Optional newlines after section headers
  • Customizable array notation (bracketed vs duplicate keys)