ini-es

ESM and TypeScript rewrite of npm/ini.

Features

• Rewritten in ESM and TypeScript, ships with type declarations
• Refactor all to pure functions, fully tree-shakable

Install

npm install ini-es

yarn add ini-es

pnpm add ini-es

bun add ini-es

Usage

import { encode, decode } from 'ini-es'

const INI_SAMPLE = `
; This comment is being ignored
scope = global

[database]
user = db_user
password = db_password
database = use_this_database

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

const decoded = decode(INI_SAMPLE)

console.log(decoded)
// => object

const encoded = encode(decoded)

console.log(encoded)
// => ini string

Node FS helpers

import { readIniFile, readIniFileSync } from 'ini-es/fs'

const config = await readIniFile('./config.ini')
const configSync = readIniFileSync('./config.ini')

These helpers strip a UTF-8 BOM if present before decoding the content.

API

encode

Encodes the given data object as an INI formatted string

• Type: (obj: AnyObject, options: string | EncodeOptions = {}): string

parameters

obj

• Type: AnyObject

Given data.

options

• Type: AnyObject
• Default: {}
• Required: false

Encode options.

stringify

Alias of encode.

decode

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

• Type: <T extends AnyObject = AnyObject>(text: string, options: DecodeOptions = {}): T

parameters

text

• Type: string

Ini string.

options

• Type: AnyObject
• Default: {}
• Required: false

Decode options.

parse

Alias of decode.

Interface

export interface EncodeOptions {
  /**
   * Whether to align the `=` character for each section.
   *
   * -> Also enables the `whitespace` option
   *
   * @default false
   */
  align?: boolean

  /**
   * Whether to append `[]` to array keys.
   *
   * Some parsers treat duplicate names by themselves as arrays
   *
   * @default true
   */
  bracketedArray?: boolean

  /**
   * Whether to insert a newline after each section header.
   *
   * The TOSHIBA & FlashAir parser require this format.
   *
   * @default false
   */
  newline?: boolean

  /**
   * Which platforms line-endings should be used.
   *
   * win32 -> CR+LF
   * other -> LF
   *
   * Default is the current platform
   *
   * @default process.platform
   */
  platform?: Platform

  /**
   * Specify section to decode
   */
  section?: string

  /**
   * Whether to sort all sections & their keys alphabetically.
   *
   * @default false
   */
  sort?: boolean

  /**
   * Whether to insert spaces before & after `=`
   *
   * Disabled by default to have better
   * compatibility with old picky parsers.
   *
   * @default false
   */
  whitespace?: boolean
}

/**
 * Type of `process.platform`
 */
type Platform =
  | 'aix'
  | 'android'
  | 'cygwin'
  | 'darwin'
  | 'freebsd'
  | 'haiku'
  | 'linux'
  | 'netbsd'
  | 'openbsd'
  | 'sunos'
  | 'win32'

export interface DecodeOptions {
  /**
   * Whether to append `[]` to array keys.
   * Some parsers treat duplicate names by themselves as arrays
   *
   * @default true
   */
  bracketedArray?: boolean
}

License

MIT License © 2025-PRESENT ntnyq