yini-parser
Version:
Readable configuration without YAML foot-guns or JSON noise. The official Node.js parser for YINI config format — An INI-inspired configuration format with clear nesting, explicit types, and predictable parsing.
195 lines (194 loc) • 10.8 kB
TypeScript
import { ParsedObject, ParseOptions, PreferredFailLevel, YiniParseResult } from './types';
/**
* This class is the public API, which exposes only parse(..) and
* parseFile(..), rest of the implementation details are hidden.
* @note Only parse and parseFile are public.
*/
export default class YINI {
private static g_tabSize;
/**
* @returns The number of spaces per tab character used in error messages.
*/
static getTabSize(): number;
/**
* Overrides the number of spaces per tab character used in error messages.
* Allowed range: 1-32.
*/
static setTabSize(spaces: number): void;
/**
* Parse inline YINI content into a JavaScript object.
*
* @param yiniContent YINI code as a string (multi‑line content supported).
* @param strictMode If `true`, enforce strict parsing rules (e.g. require `/END`, disallow trailing commas).
* @param failLevel Preferred bail sensitivity level, controls if and when parsing should stop on problems:
* - `'auto'` (default) : Auto‑select level (strict → `'errors'`, lenient → `'ignore-errors'`)
* - `'ignore-errors'` : Continue parsing despite errors; log them and attempt recovery.
* - `'errors'` : Stop parsing on the first error (fail-fast).
* - `'warnings-and-errors'` : Stop parsing on the first warning **or** error.
* @param includeMetadata If `true`, return additional metadata (e.g. warnings, statistics) alongside the parsed object.
*
* @returns {ParsedObject | YiniParseResult} The parsed YINI content.
*
* By default (`includeMetadata = false`), this method returns a plain JavaScript object:
*
* `
* export type ParsedObject = any
* `
*
* If `includeMetadata = true`, the return value is wrapped in a container that also
* includes parsing metadata:
*
* `
* export interface YiniParseResult {
* result: ParsedObject
* meta: ResultMetadata
* }
* `
*/
static parse(yiniContent: string, strictMode?: boolean, failLevel?: PreferredFailLevel, includeMetadata?: boolean): ParsedObject | YiniParseResult;
/**
* Parse inline YINI content into a JavaScript object, using an options object for configuration.
*
* @param yiniContent YINI code as a string (multi‑line content supported).
* @param options Optional settings to customize parsing and/or results, useful if you need more control.
* For all options, see types/ParseOptions.
*
* @param options.failLevel - Preferred bail sensitivity level, controls if and when parsing should stop on problems:
* Accepts:
* `'ignore-errors'` - Continue despite errors, persist and try to recover.
* `'errors'` - Stop parsing on the first error (fail-fast).
* `'warnings-and-errors'` - Stop parsing on the first warning or error.
* (Type: TPreferredFailLevel; exact behavior is implementation-defined.)
* @param options.includeDiagnostics - Include diagnostics in the returned metadata.
* Requires: `includeMetadata = true`. Ignored otherwise.
* @param options.includeMetadata - Attach a metadata object to the parse result
* (e.g., timings, diagnostics).
* @param options.includeTiming - Include timing information for parser phases in metadata.
* Requires: `includeMetadata = true`. Ignored otherwise.
* @param options.onDuplicateKey - Strategy/handler when encountering a duplicate key.
* Allowed values: `'warn-and-keep-first'` | `'warn-and-overwrite'` | `'keep-first'` (silent, first wins) | `'overwrite'` (silent, last wins) | `'error'`.
* @param options.preserveUndefinedInMeta - Keep properties with value `undefined` inside
* the returned metadata. Requires: `includeMetadata = true`. Ignored otherwise.
* @param options.quiet - Show only errors, will suppress warnings and messages sent to the console/log.
* Does not affect warnings included in returned metadata.
* @param options.requireDocTerminator - Controls whether a document terminator is required.
* Allowed values: `'optional'` | `'warn-if-missing'` | `'required'`.
* @param options.silent - Suppress all output (even errors, exit code only).
* @param options.strictMode - Sets the baseline ruleset (true = strict, false = lenient).
* This is only a starting point: rule-specific options (e.g., `treatEmptyValueAsNull`,
* `onDuplicateKey`, etc.) can override parts of that ruleset. If any overrides are given,
* the effective mode becomes **custom** rather than purely strict/lenient.
* @param options.treatEmptyValueAsNull - How to treat an explicitly empty value on the
* right-hand side of '='. Allowed values: `'allow'` | `'allow-with-warning'` | `'disallow'`.
* @param options.throwOnError - Will throw on first parse error encountered.
* NOTE: Current default is `true`. The default will change to `false` in the next
* release. To avoid breaking changes, set this option explicitly.
*
* @returns {ParsedObject | YiniParseResult} The parsed YINI content.
*
* By default (`includeMetadata = false`), this method returns a plain JavaScript object:
*
* `
* export type ParsedObject = any
* `
*
* If `includeMetadata = true`, the return value is wrapped in a container that also
* includes parsing metadata:
*
* `
* export interface YiniParseResult {
* result: ParsedObject
* meta: ResultMetadata
* }
* `
*/
static parse(yiniContent: string, options?: ParseOptions): ParsedObject | YiniParseResult;
/**
* Parse a YINI file into a JavaScript object.
*
* @param yiniFile Path to the YINI file.
* @param strictMode If `true`, enforce strict parsing rules (e.g. require `/END`, disallow trailing commas).
* @param failLevel Preferred bail sensitivity level, controls if and when parsing should stop on problems:
* - `'auto'` (default) : Auto‑select level (strict → `'errors'`, lenient → `'ignore-errors'`)
* - `'ignore-errors'` : Continue parsing despite errors; log them and attempt recovery.
* - `'errors'` : Stop parsing on the first error (fail-fast).
* - `'warnings-and-errors'` : Stop parsing on the first warning **or** error.
* @param includeMetadata If `true`, return additional metadata (e.g. warnings, statistics) alongside the parsed object.
*
* @returns {ParsedObject | YiniParseResult} The parsed YINI content.
*
* By default (`includeMetadata = false`), this method returns a plain JavaScript object:
*
* `
* export type ParsedObject = any
* `
*
* If `includeMetadata = true`, the return value is wrapped in a container that also
* includes parsing metadata:
*
* `
* export interface YiniParseResult {
* result: ParsedObject
* meta: ResultMetadata
* }
* `
*/
static parseFile(filePath: string, strictMode?: boolean, failLevel?: PreferredFailLevel, includeMetadata?: boolean): ParsedObject | YiniParseResult;
/**
* Parse a YINI file into a JavaScript object, using an options object for configuration.
*
* @param yiniFile Path to the YINI file.
* @param options Optional settings to customize parsing and/or results, useful if you need more control.
* For all options, see types/ParseOptions.
*
* @param options.failLevel - Preferred bail sensitivity level, controls if and when parsing should stop on problems:
* Accepts:
* `'ignore-errors'` - Continue despite errors, persist and try to recover.
* `'errors'` - Stop parsing on the first error (fail-fast).
* `'warnings-and-errors'` - Stop parsing on the first warning or error.
* (Type: TPreferredFailLevel; exact behavior is implementation-defined.)
* @param options.includeDiagnostics - Include diagnostics in the returned metadata.
* Requires: `includeMetadata = true`. Ignored otherwise.
* @param options.includeMetadata - Attach a metadata object to the parse result
* (e.g., timings, diagnostics).
* @param options.includeTiming - Include timing information for parser phases in metadata.
* Requires: `includeMetadata = true`. Ignored otherwise.
* @param options.onDuplicateKey - Strategy/handler when encountering a duplicate key.
* Allowed values: `'warn-and-keep-first'` | `'warn-and-overwrite'` | `'keep-first'` (silent, first wins) | `'overwrite'` (silent, last wins) | `'error'`.
* @param options.preserveUndefinedInMeta - Keep properties with value `undefined` inside
* the returned metadata. Requires: `includeMetadata = true`. Ignored otherwise.
* @param options.quiet - Show only errors, will suppress warnings and messages sent to the console/log.
* Does not affect warnings included in returned metadata.
* @param options.requireDocTerminator - Controls whether a document terminator is required.
* Allowed values: `'optional'` | `'warn-if-missing'` | `'required'`.
* @param options.silent - Suppress all output (even errors, exit code only).
* @param options.strictMode - Sets the baseline ruleset (true = strict, false = lenient).
* This is only a starting point: rule-specific options (e.g., `treatEmptyValueAsNull`,
* `onDuplicateKey`, etc.) can override parts of that ruleset. If any overrides are given,
* the effective mode becomes **custom** rather than purely strict/lenient.
* @param options.treatEmptyValueAsNull - How to treat an explicitly empty value on the
* right-hand side of '='. Allowed values: `'allow'` | `'allow-with-warning'` | `'disallow'`.
* @param options.throwOnError - Will throw on first parse error encountered.
* NOTE: Current default is `true`. The default will change to `false` in the next
* release. To avoid breaking changes, set this option explicitly.
*
* @returns {ParsedObject | YiniParseResult} The parsed YINI content.
*
* By default (`includeMetadata = false`), this method returns a plain JavaScript object:
*
* `
* export type ParsedObject = any
* `
*
* If `includeMetadata = true`, the return value is wrapped in a container that also
* includes parsing metadata:
*
* `
* export interface YiniParseResult {
* result: ParsedObject
* meta: ResultMetadata
* }
* `
*/
static parseFile(filePath: string, options?: ParseOptions): ParsedObject | YiniParseResult;
}