@std/ini
This @std package is experimental and its API may change without a major version bump.
Overview Jump to heading
parse and stringify for handling
INI encoded data, such as the
Desktop Entry specification.
Values are parsed as strings by default to preserve data parity from the original.
Customization is possible in the form of reviver/replacer functions like those in JSON.parse and JSON.stringify.
Nested sections, repeated key names within a section, and key/value arrays are not supported,
but will be preserved when using IniMap. Multi-line values are not supported and will throw a syntax error.
White space padding and lines starting with '#', ';', or '//' will be treated as comments.
import * as ini from "@std/ini";
import { assertEquals } from "@std/assert";
const iniFile = `# Example configuration file
Global Key=Some data here
[Section #1]
Section Value=42
Section Date=1977-05-25`;
const parsed = ini.parse(iniFile, {
reviver(key, value, section) {
if (section === "Section #1") {
if (key === "Section Value") return Number(value);
if (key === "Section Date") return new Date(value);
}
return value;
},
});
assertEquals(parsed, {
"Global Key": "Some data here",
"Section #1": {
"Section Value": 42,
"Section Date": new Date("1977-05-25T00:00:00.000Z"),
},
});
const text = ini.stringify(parsed, {
replacer(key, value, section) {
if (section === "Section #1" && key === "Section Date") {
return (value as Date).toISOString().split("T")[0];
}
return value;
},
});
assertEquals(text, `Global Key=Some data here
[Section #1]
Section Value=42
Section Date=1977-05-25`);
Optionally, IniMap may be used for finer INI handling. Using this class will permit preserving
comments, accessing values like a map, iterating over key/value/section entries, and more.
import { IniMap } from "@std/ini/ini-map";
import { assertEquals } from "@std/assert";
const ini = new IniMap();
ini.set("section1", "keyA", 100);
assertEquals(ini.toString(), `[section1]
keyA=100`);
ini.set('keyA', 25)
assertEquals(ini.toObject(), {
keyA: 25,
section1: {
keyA: 100
}
});
The reviver and replacer APIs can be used to extend the behavior of IniMap, such as adding support for duplicate keys as if they were arrays of values.
import { IniMap } from "@std/ini/ini-map";
import { assertEquals } from "@std/assert";
const iniFile = `# Example of key/value arrays
[section1]
key1=This key
key1=is non-standard
key1=but can be captured!`;
const ini = new IniMap({ assignment: "=", deduplicate: true });
ini.parse(iniFile, (key, value, section) => {
if (section) {
if (ini.has(section, key)) {
const exists = ini.get(section, key);
if (Array.isArray(exists)) {
exists.push(value);
return exists;
} else {
return [exists, value];
}
}
}
return value;
});
assertEquals(
ini.get("section1", "key1"),
["This key", "is non-standard", "but can be captured!"]
);
const result = ini.toString((key, value) => {
if (Array.isArray(value)) {
return value.join(
`${ini.formatting.lineBreak}${key}${ini.formatting.assignment}`,
);
}
return value;
});
assertEquals(result, iniFile);
Add to your project Jump to heading
deno add jsr:@std/ini
See all symbols in @std/ini on
What is an INI file? Jump to heading
INI files are simple text files used for configuration. They consist of key-value pairs grouped into sections, making them easy to read and edit by humans. INI files are commonly used for application settings, preferences, and other configuration data.
Why use @std/ini? Jump to heading
- INI is loosely specified; favor simple key/value usage and flat sections for best interoperability.
- Values parse as strings by default. Use reviver/replacer to coerce to numbers/dates/booleans explicitly.
- Multi-line values and arrays aren’t standard; use
IniMapplus custom reviver/replacer to emulate if needed. - Comments begin with
#,;, or//and are preserved byIniMap.
Examples Jump to heading
Coercing types
import * as ini from "@std/ini";
const cfg = ini.parse(text, {
reviver(key, value) {
if (/^(true|false)$/i.test(value)) return value.toLowerCase() === "true";
if (/^\d+$/.test(value)) return Number(value);
return value;
},
});
Custom assignment operator and pretty formatting
import * as ini from "@std/ini";
const txt = `name: Deno\nversion: 1`;
// Use ':' instead of '=' when parsing
const parsed = ini.parse(txt, { assignment: ":" });
// And keep using ':' and pretty spacing on write
const out = ini.stringify(parsed, { assignment: ":", pretty: true });
// out => "name : Deno\nversion : 1"
Preserve comments and order with IniMap
import { IniMap } from "@std/ini/ini-map";
const text = `# Global
[app]
# Port to listen on
port=8080`;
const im = new IniMap();
im.parse(text);
// Modify a value while preserving comments and ordering
im.set("app", "port", "9090");
// Comments and structure are kept in the output
const roundTrip = im.toString();
Merge layered configs (base + local overrides)
import { IniMap } from "@std/ini/ini-map";
const baseText = `[db]\nhost=localhost\nport=5432\n[app]\nmode=prod`;
const localText = `[db]\nport=6543\n[app]\nmode=dev`;
const base = new IniMap();
base.parse(baseText);
const local = new IniMap();
local.parse(localText);
// Overlay values from local onto base
const overlay = (target: IniMap, source: IniMap) => {
const obj = source.toObject() as Record<string, unknown>;
for (const [k, v] of Object.entries(obj)) {
if (v && typeof v === "object" && !Array.isArray(v)) {
for (const [kk, vv] of Object.entries(v as Record<string, string>)) {
target.set(k, kk, vv);
}
} else {
target.set(k, v as string);
}
}
};
overlay(base, local);
const merged = base.toString();
Duplicate keys: last-wins vs preservation
import * as ini from "@std/ini";
import { IniMap } from "@std/ini/ini-map";
const dup = `x=1\nx=2`;
// Simple parse: last value wins
const simple = ini.parse(dup); // { x: "2" }
// Using IniMap preserves duplicates (you can implement custom handling)
const im = new IniMap({ deduplicate: true });
im.parse(dup);
// e.g. im.get("x") returns "2" by default; use a custom reviver to collect all