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.
128 lines (127 loc) • 4.23 kB
TypeScript
/**
* Internal types ONLY, public (user-facing) type should go into src/types/index.ts.
*
* @note
* The use of null vs undefined
* ----------------------------
* The convention here (in this file) is:
* - undefined is used where a value is missing, or does not apply.
* - null is used where a value is missing or has not yet been computed.
*
* @note All names of **internal** types and interfaces (shapes) must be
* prefixed with `T` or `I`.
*/
import { DocumentTerminatorRule, DuplicateKeyPolicy, EmptyValueRule, OnDuplicateKey, PreferredFailLevel } from '../types';
export type TParserMode = 'lenient' | 'strict';
export type TExactMode = 'custom' | TParserMode;
export type TSourceType = 'File' | 'Inline';
export type TSubjectType = 'None/Ignore' | TSourceType;
export type TBailSensitivityLevel = '0-Ignore-Errors' | '1-Abort-on-Errors' | '2-Abort-Even-on-Warnings';
/**
* Scalar literal, a single, indivisible piece of data:
* string, number, boolean, and null.
* @property {string | undefined} [tag]
* Its contents may change at any time and should not
* be relied upon for any significant purpose.
* @note Undefined is included here despite that JSON cannot represent
* it (undefined), but JS objects can (it's sometimes useful in
* debugging etc), it will later get stripped if converted into JSON.
*/
export type TScalarValue = {
type: 'String';
value: string;
tag: string | undefined;
} | {
type: 'Number';
value: number;
tag: string | undefined;
} | {
type: 'Boolean';
value: boolean;
tag: string | undefined;
} | {
type: 'Null';
value: null;
tag: string | undefined;
} | {
type: 'Undefined';
value: undefined;
tag: string | undefined;
};
/** Any literal value in YINI: scalar, list, or object. */
export type TValueLiteral = TScalarValue | TListValue | TObjectValue;
/**
* @property {string | undefined} [tag]
* Debugging only. Its contents may change at any time and
* must not be relied upon for any functional purpose.
*/
export type TListValue = {
type: 'List';
elems: readonly TValueLiteral[];
tag: string | undefined;
};
/**
* @property {string | undefined} [tag]
* Debugging only. Its contents may change at any time and
* must not be relied upon for any functional purpose.
*/
export type TObjectValue = {
type: 'Object';
entries: Readonly<Record<string, TValueLiteral>>;
tag: string | undefined;
};
export type TSectionHeaderType = undefined | 'Classic-Header-Marker' | 'Numeric-Header-Marker';
export type TIssueType = 'Fatal-Error' | 'Internal-Error' | 'Syntax-Error' | 'Syntax-Warning' | 'Notice' | 'Info';
interface IMetaBaseInfo {
sourceType: TSourceType;
fileName: string | undefined;
}
/**
* Internal runtime info / meta data.
* @note Used for internal diagnostics, bookkeeping, state, etc.
*/
export interface IRuntimeInfo extends IMetaBaseInfo {
lineCount: number | null;
fileByteSize: number | null;
timeIoMs: number | null;
preferredBailSensitivity: null | PreferredFailLevel;
sha256: string | null;
}
export interface IParseCoreOptions {
rules: IParseRuleOptions;
bailSensitivity: TBailSensitivityLevel;
isIncludeMeta: boolean;
isWithDiagnostics: boolean;
isWithTiming: boolean;
isKeepUndefinedInMeta: boolean;
isQuiet: boolean;
isSilent: boolean;
isThrowOnError: boolean;
}
export interface IParseRuleOptions {
initialMode: 'custom' | TParserMode;
onDuplicateKey: DuplicateKeyPolicy;
requireDocTerminator: DocumentTerminatorRule;
treatEmptyValueAsNull: EmptyValueRule;
}
export interface IYiniAST extends IMetaBaseInfo {
root: IYiniSection;
isStrict: boolean;
terminatorSeen: boolean;
yiniMarkerSeen: boolean;
maxDepth: number | null;
numOfSections: number;
numOfMembers: number;
sectionNamePaths: string[] | null;
}
export interface IYiniSection {
sectionName: string;
level: number;
members: Map<string, TValueLiteral>;
children: IYiniSection[];
}
export interface IBuildOptions {
mode?: 'lenient' | 'strict';
onDuplicateKey?: OnDuplicateKey;
}
export {};