yini-parser 1.0.2-beta → 1.2.0-beta

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # CHANGELOG
 
+## --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.  
+- **Build logic reimplemented** (`core/objectBuilder.ts`) for improved reliability and consistency.  
+- **Error reporting enhanced** to be more user-friendly and informative.  
+- **Fixed bug sometimes wrong line** Sometimes incorrect line number in error messages are now reported accurately.
+- Renamed option `bailSensitivity` to a more shorter and user-friendly name `failLevel`.
+- **Extended `parse` and `parseFile` methods** to support an options-object form.  
+  Example:
+  ```ts
+  const config= YINI.parse(yini, {
+            strictMode: false,
+            failLevel: 'auto',
+            includeMetadata: false,
+            requireDocTerminator: false,
+        })  
+  ```  
+### Specification Alignment
+- Updated to follow the **latest YINI specification (v1.0.0-rc.3)**.  
+  - Document terminator `/END` is now optional in both lenient and strict mode.
+### Meta Data
+- The optional returned **meta data structure** has been redesigned.  
+  - Now includes improved organization.  
+  - **Timing support** added for detailed performance insight.
+  - Grouping with **source**, **structure**, **diagnostics**, etc.
+
 ## 1.0.2-beta - 2025 Aug
 - Fixed issues with floats, including negative and exponential numbers with new test files here: `tests/fixed-issues/issue-32/*`
 - Fixed an issue where parseFile(..) did not output a warning when parsing a file missing a newline at EOF. Plus added test cases to check that it is fixed (in `tests/fixed-issues/issue-30`).

package/README.md

@@ -21,7 +21,7 @@ YINI (Yet another INI): YINI is a configuration format designed for readability
 
 ---
 
-## YINI Parser – TypeScript
+## YINI Parser – (source code in TypeScript)
 
 > 🚧 This package is in **beta**. The core API is stabilizing, some more advanced features may still change. Feedback and bug reports are welcome!
 
@@ -58,20 +58,25 @@ YINI is a simple, human-friendly configuration format inspired by INI and JSON.
 
 ## Quick Start
 
-A minimal example using YINI in TypeScript:
+A small example using YINI in TypeScript/JavaScript:
 ```ts
 import YINI from 'yini-parser'
 
 const config = YINI.parse(`
-^ App
-name     = 'My Title'    // App display name.
-items    = 25
-darkMode = true
-
-    // Sub-section of App.
-    ^^ Special
-    primaryColor = #336699
-    isCaching = false
+    // YINI is a simple, human-readable configuration file format.
+
+    // Note: In YINI, spaces and tabs don't change meaning - 
+    // indentation is just for readability.
+
+    ^ App                      // Definition of section (group) "App" 
+      name     = 'My Title'    // Keys and values are written as key = value
+      items    = 25
+      darkMode = true          // "ON" and "YES" works too
+
+        // Sub-section of the "App" section
+        ^^ Special
+           primaryColor = #336699   // Hex number format
+           isCaching    = false     // "OFF" and "NO" works too
 `)
 
 // To parse from a file instead:
@@ -89,15 +94,15 @@ My Title
 false
 
 {
-  App: {
-    name: 'My Title',
-    items: 25,
-    darkMode: true,
-    Special: { 
-      primaryColor: 3368601,
-      isCaching: false
+    App: {
+        name: 'My Title',
+        items: 25,
+        darkMode: true,
+        Special: { 
+            primaryColor: 3368601,
+            isCaching: false
+        }
     }
-  }
 }
 ```
 
@@ -229,45 +234,44 @@ These examples are also included in the npm package.
 
 ---
 
-## Advanced Example
+## Bigger Example
 
 ```js
 const YINI = require('yini-parser').default; // Or: import YINI from 'yini-parser';
 
 const config = YINI.parse(`
-    /*
-        This is a multi-line block comment.
+    // This is a comment in YINI
+    // YINI is a simple, human-readable configuration file format.
+
+    // Note: In YINI, spaces and tabs don't change meaning - indentation is just
+    // for readability.
+
+    /*  This is a block comment
+
+        In YINI, section headers use repeated characters "^" at the start to
+        show their level: (Section header names are case-sensitive.)
+
+        ^ SectionLevel1
+        ^^ SectionLevel2
+        ^^^ SectionLevel3
     */
 
-    @yini
+    ^ App                           // Definition of section (group) "App" 
+      title = 'My App'
+      items = 25
+      debug = ON                    // "true" and "YES" works too
 
-    ^ App
-    name = "Nested Example"
-    version = "1.0.0"
-    debug = OFF  // This is a comment.
-
-        # Database settings.
-        ^^ Database
-        host = "db.example.com"
-        port = 3306
-        user = "appuser"
-        --password = "dbpassword"  # Disabled line due to --.
-        //password = "dbpassword"  # Not sure yet about this pw.
-        password = "dbpassword"  # Keep this secret.
-
-            // Commenting with slashes works too.
-            ^^^ Pool
-            min = 2
-            max = 10
-            idleTimeout = 300
-
-        /* Block comment on a single line. */
-        ^^ Logging
-        level = "info"
-        logToFile = ON # This is a comment.
-        filePath = "./logs/app.log"
+    ^ Server                        // Definition of section (group) "Server"
+      host = 'localhost'
+      port = 8080
+      useTLS = OFF                  // "false" and "NO" works too
+
+        // Sub-section of "Server"
+        ^^ Login
+          username = 'user_name'
+          password = 'your_password_here'
     
-    /END
+    /END // (only optional)
 `);
 
 console.log(config);
@@ -278,60 +282,41 @@ console.log(config);
 // JS object
 {
     App: {
-        name: "Nested Example",
-        version: "1.0.0",
-        debug: false,
-        Database: {
-            host: "db.example.com",
-            port: 3306,
-            user: "appuser",
-            password: "dbpassword",
-            Pool: {
-                min: 2,
-                max: 10,
-                idleTimeout: 300
-            }
-        },
-        Logging: {
-            level: "info",
-            logToFile: true,
-            filePath: "./logs/app.log"
+        title: 'My App', 
+        items: 25, 
+        debug: true
+    },
+    Server: {
+        host: 'localhost',
+        port: 8080,
+        useTLS: false,
+        Login: { 
+            username: 'user_name', 
+            password: 'your_password_here'
         }
     }
 }
 ```
 
----
-
-## API
-
-Only the `YINI` class is exposed in the public API, with two static methods: `parse` and `parseFile`.
-
-### `YINI.parse(yiniContent: string, strictMode?: boolean, bailSensitivity: 'auto' | 0 | 1 | 2 = "auto", includeMetaData = false): object`
-
-Parses YINI code from a string.  
-
-**Params:**
-- `yiniContent`: The YINI configuration as a string.
-- `strictMode`: (optional, default `false`) Parse in strict mode.
-- `bailSensitivity`: (optional, default `"auto"`) Error tolerance level.
-  * If `bailSensitivity` is `"auto"` then bail sensitivity level will be set to 0 if in non-strict mode, if in strict mode then level 1 will be used automatically.
-- `includeMetaData`: If true then additional meta data will be returned along the object.
-
-**Bail sensitivity levels:**
-- 0 = 'Ignore-Errors' // Don't bail on errors, persist and try to recover.
-- 1 = 'Abort-on-Errors'
-- 2 = 'Abort-Even-on-Warnings'
-
-Returns a JavaScript object representing the parsed configuration (YINI content).
-
-### `YINI.parseFile(filePath: string, strictMode?: boolean, bailSensitivity: 'auto' | 0 | 1 | 2 = "auto", includeMetaData = false): object`
-
-Parses YINI code from a file.
-- `filePath`: Path to the `.yini` file.
-- Other parameters are the same as `parse(..)`.
-
-Returns a JavaScript object representing the parsed YINI configuration file.
+### Output in JSON:
+```json
+{
+    "App": {
+        "title": "My App",
+        "items": 25,
+        "debug": true
+    },
+    "Server": {
+        "host": "localhost",
+        "port": 8080,
+        "useTLS": false,
+        "Login": {
+            "username": "user_name",
+            "password": "your_password_here"
+        }
+    }
+}
+```
 
 ---
 

package/dist/YINI.d.ts

@@ -1,43 +1,182 @@
-import { TJSObject } 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.
  * @note Only parse and parseFile are public.
  */
 export default class YINI {
-    static filePath: string;
+    private static g_tabSize;
     /**
-     * Parse YINI content into a JavaScript object.
+     * @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 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?: 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 strictMode       If `true`, enforce strict parsing rules (e.g. require `/END`, disallow trailing commas).
-     * @param bailSensitivity  Controls how errors and warnings are handled:
-     *   - `'auto'`               : 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.
+     * @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.
      *
-     * @note The order of properties in each output object may differ from their order in the YINI source.
+     * By default (`includeMetadata = false`), this method returns a plain JavaScript object:
      *
-     * @returns A JavaScript object representing the parsed YINI content.
+     * `
+     * 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, bailSensitivity?: "auto" | 0 | 1 | 2, includeMetaData?: boolean) => 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 → `'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?: 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 strictMode       If `true`, enforce strict parsing rules (e.g. require `/END`, disallow trailing commas).
-     * @param bailSensitivity  Controls how errors and warnings are handled:
-     *   - `'auto'`               : 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.
+     * @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
+     * `
      *
-     * @note The order of properties in each output object may differ from their order in the YINI source.
+     * 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, strictMode?: boolean, bailSensitivity?: "auto" | 0 | 1 | 2, includeMetaData?: boolean) => TJSObject;
+    static parseFile(filePath: string, options?: AllUserOptions): ParsedObject | YiniParseResult;
 }