yini-parser 1.1.0-beta → 1.2.0-beta

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## --dev/uppcoming--
 
+## 1.2.0-beta - 2025 Sep
+- **Fixed:** `parseFile()` now correctly passes through all options (e.g. `includeDiagnostics`) so they work and matches as in `parse(..)`.
+- **Fixed:** typo (`in in`) in file parsing error message.
+- **Updated:** metadata structure bumped to version 1.1.0, and below added (among other things):
+    ```ts
+    preservesOrder: true // Member/section order: platform-, implementation-, and language-specific. Not mandated by the YINI spec.
+    orderGuarantee: 'implementation-defined'
+    orderNotes?: string
+    ```
+- **Refactored:** the static public (user-facing) YINI class to use per-invocation runtime state, preventing race conditions in runtime info when multiple calls to `parse(..)` / `parseFile(..)` run in parallel.
+- **Refactored file layout:** Moved and renamed files in `src/`
+  * File `src/parseEntry.ts` renamed and moved to `src/src/pipeline.ts`, 
+      - And in that file, rename the method/function `_parseEntry(..)` to `runPipeline(..)`.
+  * Renamed the file `core/types.ts` to `core/internalTypes.ts`
+      - And moved public (user-facing) types and interfaces into its own file `src/types/index.ts`.
+  * Moved the file `src/yiniHelpers.ts` to `src/utils/yiniHelpers.ts`.
+- **Renamed:** `includeMetaData` to `includeMetadata`.
+- **Updated:** Codebase now consistently uses the `ParsedObject` type,
+replacing the older `TJSObject` type for representing parsed YINI.
+- **Docs:** Expanded and improved TSDoc of several of the functions in the public API.
+- **Internal:** Unit tests are now colocated with their source code files in `src/**`. So there is 1:1 visibility between code and its unit tests, and less chance of missing coverage, etc.
+
 ## 1.1.0-beta - 2025 Sep
 ### Parser
 - **Reimplemented parser from scratch** (`core/ASTBuilder.ts`) using the refactored grammar for a much cleaner and more maintainable design.  
@@ -15,7 +37,7 @@
   const config= YINI.parse(yini, {
             strictMode: false,
             failLevel: 'auto',
-            includeMetaData: false,
+            includeMetadata: false,
             requireDocTerminator: false,
         })  
   ```  

package/dist/YINI.d.ts

@@ -1,4 +1,4 @@
-import { IAllUserOptions, TJSObject, TPreferredFailLevel } from './core/types';
+import { AllUserOptions, ParsedObject, PreferredFailLevel, YiniParseResult } from './types';
 /**
  * This class is the public API, which exposes only parse(..) and
  * parseFile(..), rest of the implementation details are hidden.
@@ -18,49 +18,165 @@ export default class YINI {
     /**
      * 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 how errors and warnings are handled:
-     *   - `'auto'` (default)       : Auto‑select level (strict→1, lenient→0)
-     *   - `0` / `'Ignore-Errors'`    : Continue parsing despite errors; log them and attempt recovery.
-     *   - `1` / `'Abort-on-Errors'`  : Stop parsing on the first error.
-     *   - `2` / `'Abort-Even-on-Warnings'`: Stop parsing on the first warning **or** error.
-     * @param includeMetaData  If `true`, return additional metadata (e.g. warnings, statistics) alongside the parsed object.
-     *
-     * @returns A JavaScript object representing the parsed YINI content.
+     * @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 how errors and warnings are handled:
+     *   - `'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.
+     *   - `'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 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?: TPreferredFailLevel, includeMetaData?: boolean): TJSObject;
+    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/IAllUserOptions.
+     *
+     * @param options.failLevel - Minimum severity that should cause the parse to fail.
+     *   Accepts:
+     *     `'ignore-errors'` - Don't bail/fail on error, persist and try to recover.
+     *     `'errors'` - Stop parsing on the first error.
+     *     `'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.requireDocTerminator - Controls whether a document terminator is required.
+     *   Allowed values: `'optional'` | `'warn-if-missing'` | `'required'`.
+     * @param options.strictMode - Enable stricter syntax and well-formedness checks according
+     *   to the spec (exact rules are implementation-defined).
+     * @param options.suppressWarnings - Suppress warnings sent to the console/log.
+     *   Does not affect warnings included in returned metadata.
+     * @param options.treatEmptyValueAsNull - How to treat an explicitly empty value on the
+     *   right-hand side of '='. Allowed values: `'allow'` | `'allow-with-warning'` | `'disallow'`.
+     *
+     * @returns 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:
      *
-     * @returns A JavaScript object representing the parsed YINI content.
+     * `
+     * export interface YiniParseResult {
+     *   result: ParsedObject
+     *   meta: ResultMetadata
+     * }
+     * `
      */
-    static parse(yiniContent: string, options?: IAllUserOptions): TJSObject;
+    static parse(yiniContent: string, options?: AllUserOptions): 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 how errors and warnings are handled:
-     *   - `'auto'` (default)       : Auto‑select level (strict→1, lenient→0)
-     *   - `0` / `'Ignore-Errors'`    : Continue parsing despite errors; log them and attempt recovery.
-     *   - `1` / `'Abort-on-Errors'`  : Stop parsing on the first error.
-     *   - `2` / `'Abort-Even-on-Warnings'`: Stop parsing on the first warning **or** error.
-     * @param includeMetaData  If `true`, return additional metadata (e.g. warnings, statistics) alongside the parsed object.
-     *
-     * @returns A JavaScript object representing the parsed YINI content.
+     * @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 how errors and warnings are handled:
+     *   - `'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.
+     *   - `'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 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?: TPreferredFailLevel, includeMetaData?: boolean): TJSObject;
+    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/IAllUserOptions.
+     *
+     * @param options.failLevel - Minimum severity that should cause the parse to fail.
+     *   Accepts:
+     *     `'ignore-errors'` - Don't bail/fail on error, persist and try to recover.
+     *     `'errors'` - Stop parsing on the first error.
+     *     `'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.requireDocTerminator - Controls whether a document terminator is required.
+     *   Allowed values: `'optional'` | `'warn-if-missing'` | `'required'`.
+     * @param options.strictMode - Enable stricter syntax and well-formedness checks according
+     *   to the spec (exact rules are implementation-defined).
+     * @param options.suppressWarnings - Suppress warnings sent to the console/log.
+     *   Does not affect warnings included in returned metadata.
+     * @param options.treatEmptyValueAsNull - How to treat an explicitly empty value on the
+     *   right-hand side of '='. Allowed values: `'allow'` | `'allow-with-warning'` | `'disallow'`.
+     *
+     * @returns 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:
      *
-     * @returns A JavaScript object representing the parsed YINI content.
+     * `
+     * export interface YiniParseResult {
+     *   result: ParsedObject
+     *   meta: ResultMetadata
+     * }
+     * `
      */
-    static parseFile(filePath: string, options?: IAllUserOptions): TJSObject;
+    static parseFile(filePath: string, options?: AllUserOptions): ParsedObject | YiniParseResult;
 }

package/dist/YINI.js

@@ -1,50 +1,20 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-const fs_1 = __importDefault(require("fs"));
-const perf_hooks_1 = require("perf_hooks");
 const env_1 = require("./config/env");
-const ErrorDataHandler_1 = require("./core/ErrorDataHandler");
-const parseEntry_1 = require("./parseEntry");
-const pathAndFileName_1 = require("./utils/pathAndFileName");
+const errorDataHandler_1 = require("./core/errorDataHandler");
+const normalizeOptions_1 = require("./core/options/normalizeOptions");
+const runtime_1 = require("./core/runtime");
 const print_1 = require("./utils/print");
-const string_1 = require("./utils/string");
 const DEFAULT_TAB_SIZE = 4; // De facto "modern default" (even though traditionally/historically it's 8).
-let _runtimeInfo = {
-    sourceType: 'Inline',
-    fileName: undefined,
-    fileByteSize: null,
-    lineCount: null,
-    timeIoMs: null,
-    preferredBailSensitivity: null,
-    sha256: null,
-};
-// Type guard: did the caller use the options-object form?
-const isOptionsObjectForm = (v) => {
-    return (v != null &&
-        typeof v === 'object' &&
-        // Note: If one wants, this can be relax to "typeof v === 'object'"
-        // but this keeps accidental booleans/strings out.
-        ('strictMode' in v ||
-            'failLevel' in v ||
-            'includeMetaData' in v ||
-            'includeDiagnostics' in v ||
-            'includeTiming' in v ||
-            'preserveUndefinedInMeta' in v ||
-            'requireDocTerminator' in v));
-};
-// Initial default values.
-const DEFAULT_OPTS = {
-    strictMode: false,
-    failLevel: 'auto',
-    includeMetaData: false,
-    includeDiagnostics: false,
-    includeTiming: false,
-    preserveUndefinedInMeta: false,
-    requireDocTerminator: false,
-};
+// let _runtimeInfo: IRuntimeInfo = {
+//     sourceType: 'Inline',
+//     fileName: undefined,
+//     fileByteSize: null,
+//     lineCount: null,
+//     timeIoMs: null,
+//     preferredBailSensitivity: null,
+//     sha256: null,
+// }
 /**
  * This class is the public API, which exposes only parse(..) and
  * parseFile(..), rest of the implementation details are hidden.
@@ -63,7 +33,8 @@ class YINI {
      */
     static setTabSize(spaces) {
         if (spaces < 1 || spaces > 32) {
-            new ErrorDataHandler_1.ErrorDataHandler('None/Ignore').pushOrBail(null, 'Fatal-Error', `Invalid tab size ${spaces} is out of range.`, 'Tab size must be between 1 and 32 spaces.');
+            new errorDataHandler_1.ErrorDataHandler('None/Ignore').pushOrBail(null, 'Fatal-Error', `Invalid tab size ${spaces} is out of range.`, 'Tab size must be between 1 and 32 spaces.');
+            throw new RangeError(`Tab size ${spaces} is out of range (1–32).`);
         }
         this.g_tabSize = spaces;
     }
@@ -71,76 +42,67 @@ class YINI {
     // Implementation method (not declared with arrow function) for both method overload signatures.
     // NOTE: Must be method declaration with NO =, arrow functions not (currently) supported for this type of method overloading.
     static parse(yiniContent, arg2, // strictMode | options
-    failLevel = DEFAULT_OPTS.failLevel, includeMetaData = DEFAULT_OPTS.includeMetaData) {
-        var _a, _b, _c, _d, _e, _f, _g, _h;
+    failLevel = 'auto', includeMetadata = false) {
         (0, print_1.debugPrint)('-> Entered static parse(..) in class YINI\n');
-        // Runtime guard to catch illegal/ambiguous calls coming from JS or any-cast code
-        if (isOptionsObjectForm(arg2) &&
-            (failLevel !== 'auto' || includeMetaData !== false)) {
-            throw new TypeError('Invalid call: when providing an options object, do not also pass positional parameters.');
-        }
-        // Normalize to a fully-required options object.
-        let userOpts;
-        // Required, makes all properties in T required, no undefined.
-        // const userOpts: Required<IAllUserOptions> = isOptionsObjectForm(arg2)
-        if (isOptionsObjectForm(arg2)) {
-            // Options-object Form.
-            /* parse = (
-                  yiniContent: string,
-                  options: IAllUserOptions,
-               )
-            */
-            userOpts = Object.assign(Object.assign({}, DEFAULT_OPTS), { strictMode: (_a = arg2.strictMode) !== null && _a !== void 0 ? _a : DEFAULT_OPTS.strictMode, failLevel: (_b = arg2.failLevel) !== null && _b !== void 0 ? _b : DEFAULT_OPTS.failLevel, includeMetaData: (_c = arg2.includeMetaData) !== null && _c !== void 0 ? _c : DEFAULT_OPTS.includeMetaData, includeDiagnostics: (_d = arg2.includeDiagnostics) !== null && _d !== void 0 ? _d : DEFAULT_OPTS.includeDiagnostics, includeTiming: (_e = arg2.includeTiming) !== null && _e !== void 0 ? _e : DEFAULT_OPTS.includeTiming, preserveUndefinedInMeta: (_f = arg2.preserveUndefinedInMeta) !== null && _f !== void 0 ? _f : DEFAULT_OPTS.preserveUndefinedInMeta, requireDocTerminator: (_g = arg2.requireDocTerminator) !== null && _g !== void 0 ? _g : DEFAULT_OPTS.requireDocTerminator });
-        }
-        else {
-            // Positional form.
-            /* parse = (
-                  yiniContent: string,
-                  strictMode?: boolean,
-                  failLevel?: TPreferredFailLevel,
-                  includeMetaData?: boolean,
-               )
-            */
-            userOpts = Object.assign(Object.assign({}, DEFAULT_OPTS), { strictMode: (_h = arg2) !== null && _h !== void 0 ? _h : DEFAULT_OPTS.strictMode, failLevel,
-                includeMetaData });
-        }
-        if (userOpts.includeMetaData && _runtimeInfo.sourceType === 'Inline') {
-            const lineCount = yiniContent.split(/\r?\n/).length; // Counts the lines.
-            const sha256 = (0, string_1.computeSha256)(yiniContent); // NOTE: Compute BEFORE any possible tampering of content.
-            _runtimeInfo.lineCount = lineCount;
-            _runtimeInfo.preferredBailSensitivity = userOpts.failLevel;
-            _runtimeInfo.sha256 = sha256;
-        }
-        // NOTE: Important: Do not trim or mutate the yiniContent here, due
-        // to it will mess up the line numbers in error reporting.
-        if (!yiniContent) {
-            throw new Error('Syntax-Error: Unexpected blank YINI input');
-        }
-        if (!yiniContent.endsWith('\n')) {
-            yiniContent += '\n';
-        }
-        let level = 0;
-        if (userOpts.failLevel === 'auto') {
-            if (!userOpts.strictMode)
-                level = 0;
-            if (userOpts.strictMode)
-                level = 1;
-        }
-        else {
-            level = userOpts.failLevel;
-        }
-        const coreOpts = {
-            isStrict: userOpts.strictMode,
-            bailSensitivity: level,
-            isIncludeMeta: userOpts.includeMetaData,
-            isWithDiagnostics: (0, env_1.isDev)() || (0, env_1.isDebug)() || userOpts.includeDiagnostics,
-            isWithTiming: (0, env_1.isDev)() || (0, env_1.isDebug)() || userOpts.includeTiming,
-            isKeepUndefinedInMeta: (0, env_1.isDebug)() || userOpts.preserveUndefinedInMeta,
-            isRequireDocTerminator: userOpts.requireDocTerminator,
-        };
+        // // Runtime guard to catch illegal/ambiguous calls coming from JS or any-cast code
+        // if (
+        //     isOptionsObjectForm(arg2) &&
+        //     (failLevel !== 'auto' || includeMetadata !== false)
+        // ) {
+        //     throw new TypeError(
+        //         'Invalid call: when providing an options object, do not also pass positional parameters.',
+        //     )
+        // }
+        // const mode: TParserMode = inferModeFromArgs(arg2)
+        // const defaultOptions = getDefaultOptions(mode)
+        // // Normalize to a fully-required options object.
+        // let userOpts: Required<IAllUserOptions>
+        // // Required, makes all properties in T required, no undefined.
+        // if (isOptionsObjectForm(arg2)) {
+        //     userOpts = {
+        //         ...defaultOptions, // Sets the default options.
+        //         ...arg2,
+        //     }
+        // } else {
+        //     // Positional form.
+        //     userOpts = {
+        //         ...defaultOptions, // Sets the default options.
+        //         strictMode:
+        //             (arg2 as boolean | undefined) ?? defaultOptions.strictMode,
+        //         failLevel,
+        //         includeMetadata,
+        //     }
+        // }
+        // if (userOpts.includeMetadata && _runtimeInfo.sourceType === 'Inline') {
+        //     const lineCount = yiniContent.split(/\r?\n/).length // Counts the lines.
+        //     const sha256 = computeSha256(yiniContent) // NOTE: Compute BEFORE any possible tampering of content.
+        //     _runtimeInfo.lineCount = lineCount
+        //     _runtimeInfo.preferredBailSensitivity = userOpts.failLevel
+        //     _runtimeInfo.sha256 = sha256
+        // }
+        // // NOTE: Important: Do not trim or mutate the yiniContent here, due
+        // // to it will mess up the line numbers in error reporting.
+        // if (!yiniContent) {
+        //     throw new Error('Syntax-Error: Unexpected blank YINI input')
+        // }
+        // if (!yiniContent.endsWith('\n')) {
+        //     yiniContent += '\n'
+        // }
+        // let level: TBailSensitivityLevel = mapFailLevelToBail(
+        //     userOpts.strictMode,
+        //     userOpts.failLevel,
+        // )
+        ////////////////
+        // const coreOpts: IParseCoreOptions = toCoreOptions(level, userOpts)
         (0, print_1.debugPrint)();
-        (0, print_1.debugPrint)('==== Call parse ==========================');
-        const result = (0, parseEntry_1._parseMain)(yiniContent, coreOpts, _runtimeInfo);
+        (0, print_1.debugPrint)('==== Call doParse(..) in runtime ==========================');
+        // const result = _parseMain(yiniContent, coreOpts, _runtimeInfo)
+        const runtime = new runtime_1.YiniRuntime('Inline');
+        const result = (0, normalizeOptions_1.isOptionsObjectForm)(arg2)
+            ? runtime.doParse(yiniContent, arg2) // Overload #2: (content, options)
+            : runtime.doParse(
+            // Overload #1: (content, strict?, failLevel?, includeMeta?)
+            yiniContent, arg2, failLevel, includeMetadata);
         (0, print_1.debugPrint)('==== End call parse ==========================\n');
         if ((0, env_1.isDev)()) {
             console.log();
@@ -155,73 +117,82 @@ class YINI {
     // Implementation method (not declared with arrow function) for both method overload signatures.
     // NOTE: Must be method declaration with NO =, arrow functions not (currently) supported for this type of method overloading.
     static parseFile(filePath, arg2, // strictMode | options
-    failLevel = DEFAULT_OPTS.failLevel, includeMetaData = DEFAULT_OPTS.includeMetaData) {
-        var _a, _b, _c, _d, _e, _f, _g, _h;
+    failLevel = 'auto', includeMetadata = false) {
         (0, print_1.debugPrint)('-> Entered static parseFile(..) in class YINI\n');
         (0, print_1.debugPrint)('Current directory = ' + process.cwd());
-        // Runtime guard to catch illegal/ambiguous calls coming from JS or any-cast code
-        if (isOptionsObjectForm(arg2) &&
-            (failLevel !== 'auto' || includeMetaData !== false)) {
-            throw new TypeError('Invalid call: when providing an options object, do not also pass positional parameters.');
-        }
-        // Normalize to a fully-required options object.
-        let userOpts;
-        // Required, makes all properties in T required, no undefined.
-        // const userOpts: Required<IAllUserOptions> = isOptionsObjectForm(arg2)
-        if (isOptionsObjectForm(arg2)) {
-            // Options-object Form.
-            /* parse = (
-                  yiniContent: string,
-                  options: IAllUserOptions,
-               )
-            */
-            userOpts = Object.assign(Object.assign({}, DEFAULT_OPTS), { strictMode: (_a = arg2.strictMode) !== null && _a !== void 0 ? _a : DEFAULT_OPTS.strictMode, failLevel: (_b = arg2.failLevel) !== null && _b !== void 0 ? _b : DEFAULT_OPTS.failLevel, includeMetaData: (_c = arg2.includeMetaData) !== null && _c !== void 0 ? _c : DEFAULT_OPTS.includeMetaData, includeDiagnostics: (_d = arg2.includeDiagnostics) !== null && _d !== void 0 ? _d : DEFAULT_OPTS.includeDiagnostics, includeTiming: (_e = arg2.includeTiming) !== null && _e !== void 0 ? _e : DEFAULT_OPTS.includeTiming, preserveUndefinedInMeta: (_f = arg2.preserveUndefinedInMeta) !== null && _f !== void 0 ? _f : DEFAULT_OPTS.preserveUndefinedInMeta, requireDocTerminator: (_g = arg2.requireDocTerminator) !== null && _g !== void 0 ? _g : DEFAULT_OPTS.requireDocTerminator });
-        }
-        else {
-            // Positional form.
-            /* parse = (
-                  yiniContent: string,
-                  strictMode?: boolean,
-                  failLevel?: TPreferredFailLevel,
-                  includeMetaData?: boolean,
-               )
-            */
-            userOpts = Object.assign(Object.assign({}, DEFAULT_OPTS), { strictMode: (_h = arg2) !== null && _h !== void 0 ? _h : DEFAULT_OPTS.strictMode, failLevel,
-                includeMetaData });
-        }
-        if ((0, pathAndFileName_1.getFileNameExtension)(filePath).toLowerCase() !== '.yini') {
-            console.error('Invalid file extension for YINI file:');
-            console.error(`"${filePath}"`);
-            console.log('File does not have a valid ".yini" extension (case-insensitive).');
-            throw new Error('Error: Unexpected file extension for YINI file');
-        }
-        // ---- Phase 0: I/O ----
-        const timeStartMs = perf_hooks_1.performance.now();
-        // let content = fs.readFileSync(filePath, 'utf8')
-        const rawBuffer = fs_1.default.readFileSync(filePath); // Raw buffer for size.
-        const fileByteSize = rawBuffer.byteLength; // Byte size in UTF-8.
-        let content = rawBuffer.toString('utf8');
-        const timeEndMs = perf_hooks_1.performance.now();
-        _runtimeInfo.sourceType = 'File';
-        _runtimeInfo.fileName = filePath;
-        if (userOpts.includeMetaData) {
-            _runtimeInfo.lineCount = content.split(/\r?\n/).length; // Counts the lines.
-            _runtimeInfo.fileByteSize = fileByteSize;
-            _runtimeInfo.timeIoMs = +(timeEndMs - timeStartMs);
-            _runtimeInfo.preferredBailSensitivity = userOpts.failLevel;
-            _runtimeInfo.sha256 = (0, string_1.computeSha256)(content); // NOTE: Compute BEFORE any possible tampering of content.
-        }
-        let hasNoNewlineAtEOF = false;
-        if (!content.endsWith('\n')) {
-            content += '\n';
-            hasNoNewlineAtEOF = true;
-        }
-        const result = this.parse(content, userOpts.strictMode, userOpts.failLevel, userOpts.includeMetaData);
-        if (hasNoNewlineAtEOF) {
-            console.warn(`No newline at end of file, it's recommended to end a file with a newline. File:\n"${filePath}"`);
-        }
+        // // Runtime guard to catch illegal/ambiguous calls coming from JS or any-cast code
+        // if (
+        //     isOptionsObjectForm(arg2) &&
+        //     (failLevel !== 'auto' || includeMetadata !== false)
+        // ) {
+        //     throw new TypeError(
+        //         'Invalid call: when providing an options object, do not also pass positional parameters.',
+        //     )
+        // }
+        // const mode: TParserMode = inferModeFromArgs(arg2)
+        // const defaultOptions = getDefaultOptions(mode)
+        // // Normalize to a fully-required options object.
+        // let userOpts: Required<IAllUserOptions>
+        // // Required, makes all properties in T required, no undefined.
+        // if (isOptionsObjectForm(arg2)) {
+        //     // Options-object Form.
+        //     userOpts = {
+        //         ...defaultOptions, // Sets the default options.
+        //         ...arg2,
+        //     }
+        // } else {
+        //     // Positional form.
+        //     userOpts = {
+        //         ...defaultOptions, // Sets the default options.
+        //         strictMode:
+        //             (arg2 as boolean | undefined) ?? defaultOptions.strictMode,
+        //         failLevel,
+        //         includeMetadata,
+        //     }
+        // }
+        // if (getFileNameExtension(filePath).toLowerCase() !== '.yini') {
+        //     console.error('Invalid file extension for YINI file:')
+        //     console.error(`"${filePath}"`)
+        //     console.log(
+        //         'File does not have a valid ".yini" extension (case-insensitive).',
+        //     )
+        //     throw new Error('Error: Unexpected file extension for YINI file')
+        // }
+        // // ---- Phase 0: I/O ----
+        // const timeStartMs = performance.now()
+        // // let content = fs.readFileSync(filePath, 'utf8')
+        // const rawBuffer = fs.readFileSync(filePath) // Raw buffer for size.
+        // const fileByteSize = rawBuffer.byteLength // Byte size in UTF-8.
+        // let content = rawBuffer.toString('utf8')
+        // const timeEndMs = performance.now()
+        // _runtimeInfo.sourceType = 'File'
+        // _runtimeInfo.fileName = filePath
+        // if (userOpts.includeMetadata) {
+        //     _runtimeInfo.lineCount = content.split(/\r?\n/).length // Counts the lines.
+        //     _runtimeInfo.fileByteSize = fileByteSize
+        //     _runtimeInfo.timeIoMs = +(timeEndMs - timeStartMs).toFixed(3)
+        //     _runtimeInfo.preferredBailSensitivity = userOpts.failLevel
+        //     _runtimeInfo.sha256 = computeSha256(content) // NOTE: Compute BEFORE any possible tampering of content.
+        // }
+        // let hasNoNewlineAtEOF = false
+        // if (!content.endsWith('\n')) {
+        //     content += '\n'
+        //     hasNoNewlineAtEOF = true
+        // }
+        (0, print_1.debugPrint)();
+        (0, print_1.debugPrint)('==== Call doParseFile(..) in runtime ==========================');
+        // const result = _parseMain(yiniContent, coreOpts, _runtimeInfo)
+        const runtime = new runtime_1.YiniRuntime('File');
+        const result = (0, normalizeOptions_1.isOptionsObjectForm)(arg2)
+            ? runtime.doParseFile(filePath, arg2) // Overload #2: (content, options)
+            : runtime.doParseFile(
+            // Overload #1: (content, strict?, failLevel?, includeMeta?)
+            filePath, arg2, failLevel, includeMetadata);
+        (0, print_1.debugPrint)('==== End call parse ==========================\n');
         return result;
     }
 }
+// @todo In future move/change this to not be a global and suffer from possible race conditions, possibly move this into YiniRuntime class.
 YINI.g_tabSize = DEFAULT_TAB_SIZE; // Global tab size used in error messages.
 exports.default = YINI;
+//# sourceMappingURL=YINI.js.map

package/dist/YINI.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"YINI.js","sourceRoot":"","sources":["../src/YINI.ts"],"names":[],"mappings":"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"}

package/dist/config/env.js

@@ -60,3 +60,4 @@ const isDebug = () => {
     return false;
 };
 exports.isDebug = isDebug;
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":";;;AAeA,MAAM,YAAY,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,YAAY,CAAa,CAAA;AAqE9D,oCAAY;AApErB,MAAM,WAAW,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,YAAY,CAAY,CAAA;AAoE7C,kCAAW;AAlElC,kCAAkC;AAClC,8EAA8E;AAC9E,4EAA4E;AAE5E,2CAA2C;AAC3C,IAAI;AAEJ,mDAAmD;AAEnD,gIAAgI;AACzH,MAAM,QAAQ,GAAG,GAAY,EAAE,CAAC,YAAY,KAAK,aAAa,CAAA;AAAxD,QAAA,QAAQ,YAAgD;AAErE,+HAA+H;AACxH,MAAM,SAAS,GAAG,GAAY,EAAE,CAAC,YAAY,KAAK,YAAY,CAAA;AAAxD,QAAA,SAAS,aAA+C;AAErE,6GAA6G;AACtG,MAAM,SAAS,GAAG,GAAY,EAAE,CAAC,YAAY,KAAK,MAAM,CAAA;AAAlD,QAAA,SAAS,aAAyC;AAE/D;;;;GAIG;AACI,MAAM,KAAK,GAAG,GAAY,EAAE;IAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAA;IAE/B,oEAAoE;IACpE,uDAAuD;IACvD,kCAAkC;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAW,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QACzC,IACI,GAAG,CAAC,WAAW,EAAE,KAAK,SAAS;YAC/B,GAAG,CAAC,WAAW,EAAE,KAAK,YAAY,EACpC,CAAC;YACC,OAAO,IAAI,CAAA;QACf,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAA;AAChB,CAAC,CAAA;AAjBY,QAAA,KAAK,SAiBjB;AAED;;;;GAIG;AACI,MAAM,OAAO,GAAG,GAAY,EAAE;IACjC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAA;IAE/B,oEAAoE;IACpE,uDAAuD;IACvD,kCAAkC;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAW,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QACzC,IACI,GAAG,CAAC,WAAW,EAAE,KAAK,WAAW;YACjC,GAAG,CAAC,WAAW,EAAE,KAAK,cAAc,EACtC,CAAC;YACC,OAAO,IAAI,CAAA;QACf,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAA;AAChB,CAAC,CAAA;AAjBY,QAAA,OAAO,WAiBnB"}