oldskull84-ini

A TypeScript INI file handler for Node.js with full CRUD operations, type support, and advanced features.

Installation

npm install oldskull84-ini

Features

• Full CRUD Operations - Create, read, update, and delete INI files
• Section Management - Create, rename, remove, and reorder sections
• Key-Value Pairs - Support for strings, numbers, booleans, dates, arrays, and objects
• Comments - Leading comments, section comments, and inline comments
• Global Sections - Key-value pairs before any named section
• Validation - Schema-based validation with custom rules
• Merge - Combine INI files with configurable strategies
• Async Operations - Promise-based file operations
• TypeScript - Full type definitions included

Quick Start

import IniFile from 'oldskull84-ini';
import KeyValuePair from 'oldskull84-ini/dist/models/KeyValuePair';

// Create a new INI file
const config = new IniFile('./config.ini', { overwrite: true });

// Add a section with key-value pairs
const dbSection = config.createSection('Database', 'Database settings');
dbSection.addKeyValuePair(new KeyValuePair('host', 'localhost'));
dbSection.addKeyValuePair(new KeyValuePair('port', 5432));
dbSection.addKeyValuePair(new KeyValuePair('ssl', true));

// Save to disk
config.save();

Reading INI Files

// Load from file
const config = IniFile.fromFile('./config.ini');

// Load from string
const config = IniFile.fromString(`
[Database]
host=localhost
port=5432
`);

// Get values
const host = config.getSection('Database')?.getKeyValuePair('host')?.getValue();
console.log(host); // 'localhost'

Async Operations

// Load asynchronously
const config = await IniFile.fromFileAsync('./config.ini');

// Modify
config.getSection('Database')?.updateKeyValuePair('host', 'production.db.com');

// Save asynchronously
await config.saveAsync();

// Save as new file
await config.saveAsAsync('./config.backup.ini');

// Delete file
await config.removeAsync();

Global Sections

Key-value pairs before any named section:

const config = IniFile.fromString(`
version=1.0.0
environment=production

[Database]
host=localhost
`);

const globalSection = config.getGlobalSection();
const version = globalSection?.getKeyValuePair('version')?.getValue();

Merging INI Files

import { MergeStrategy } from 'oldskull84-ini/dist/enums/MergeStrategy';

const base = IniFile.fromFile('./base.ini');
const override = IniFile.fromFile('./override.ini');

// Merge strategies:
// - MergeStrategy.Merge (default): Update existing keys, add new ones
// - MergeStrategy.Replace: Replace entire sections
// - MergeStrategy.Skip: Keep existing sections unchanged

base.merge(override, MergeStrategy.Merge);
base.save();

Validation

const config = IniFile.fromFile('./config.ini');

const result = config.validate({
  sections: {
    Database: {
      required: true,
      keys: {
        host: { required: true },
        port: { required: true, type: 'number', min: 1, max: 65535 },
        ssl: { required: false, type: 'boolean' }
      }
    }
  }
});

if (!result.isValid) {
  result.issues.forEach(issue => {
    console.log(`${issue.severity}: ${issue.message}`);
  });
}

Section Ordering

const config = IniFile.fromFile('./config.ini');

// Move section before another
config.moveSectionBefore('Logging', 'Database');

// Move section after another
config.moveSectionAfter('Cache', 'Database');

// Reorder all sections
config.reorderSections(['Database', 'Cache', 'Logging']);

Configuration Options

interface IniFileOptions {
  dateFormat?: string;           // date-fns format (default: 'yyyy-MM-dd')
  timeFormat?: string;           // date-fns format (default: 'HH:mm:ss')
  overwrite?: boolean;           // Truncate file on creation (default: false)
  booleanRepresentation?: BooleanRepresentation;  // How to serialize booleans
  commentSeparators?: string[];  // Comment characters (default: [';', '#'])
}

Boolean Representations

import { BooleanRepresentation } from 'oldskull84-ini/dist/enums/BooleanRepresentation';

// BooleanRepresentation.CamelCase: true/false
// BooleanRepresentation.PascalCase: True/False
// BooleanRepresentation.Numerics: 1/0

const config = new IniFile('./config.ini', {
  booleanRepresentation: BooleanRepresentation.CamelCase
});

API Reference

IniFile

| Method | Description | |--------|-------------| | constructor(path, options) | Create new INI file | | fromFile(path, options) | Load from file (sync) | | fromFileAsync(path, options) | Load from file (async) | | fromString(content, path?, options?) | Parse from string | | save() | Save to disk (sync) | | saveAsync() | Save to disk (async) | | saveAs(newPath) | Save to new path (sync) | | saveAsAsync(newPath) | Save to new path (async) | | remove() | Delete file (sync) | | removeAsync() | Delete file (async) | | getSection(name) | Get section by name | | getAllSections() | Get all sections | | createSection(name, comment?) | Create new section | | removeSection(name) | Remove section | | renameSection(oldName, newName) | Rename section | | sectionExists(name) | Check if section exists | | getGlobalSection() | Get global section | | createGlobalSection() | Create global section | | clearGlobalSection() | Remove global section | | merge(other, strategy?) | Merge another INI file | | validate(schema?) | Validate against schema | | moveSectionBefore(section, target) | Move section before target | | moveSectionAfter(section, target) | Move section after target | | reorderSections(names) | Reorder sections | | addLeadingComment(comment) | Add file-level comment |

IniSection

| Method | Description | |--------|-------------| | addKeyValuePair(kvp) | Add key-value pair | | getKeyValuePair(key) | Get by key | | getAllKeyValuePairs() | Get all key-value pairs | | updateKeyValuePair(key, value, comment?) | Update value | | removeKeyValuePair(key) | Remove key-value pair | | renameKeyValuePair(oldKey, newKey) | Rename key | | addCommentLine(comment) | Add comment line | | getAllCommentLines() | Get all comments | | getSectionName() | Get section name | | setSectionName(name) | Set section name |

KeyValuePair

| Method | Description | |--------|-------------| | constructor(key, value, comment?) | Create key-value pair | | getKey() | Get key | | getValue() | Get value as string | | setValue(value) | Set value | | getComments() | Get inline comment | | setComments(comment) | Set inline comment | | renameKey(newKey) | Rename key | | clearValue() | Clear value |

Supported Value Types

• String: 'hello'
• Number: 42, 3.14
• Boolean: true, false
• Date: JavaScript Date objects
• TimeOnly: Time without date
• Array: ['a', 'b', 'c'] (serialized as JSON)
• Object: { key: 'value' } (serialized as JSON)
• Null: null

License

ISC