tessl/npm-ini

An INI encoder/decoder for Node.js applications

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

INI

Name: tessl/npm-ini
Author: tessl

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)

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/ini@4.1.x
Publish Source: CLI
Badge