mason-parser 1.0.0 → 1.0.2

package/README.md

@@ -1,11 +1,37 @@
 # mason-parser
 
-> Markdown Structured Object Notation (MSON) — The human-centric serialization format that bridges natural markdown visual structure and lightweight, structured JSON.
+> Markdown Structured Object Notation (MaSON) — A human-centric serialization format bridging natural markdown visual hierarchy and structured JSON.
 
 [![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![NPM Version](https://img.shields.io/npm/v/mason-parser.svg)](https://www.npmjs.com/package/mason-parser)
 
-MSON is a super-lightweight alternative to JSON/YAML/TOML designed specifically for **configuration files**, **static content documents**, and **efficient Prompting / Context storage for Large Language Models (LLMs)**. It reduces token overhead by **15% to 30%** compared to standard JSON by replacing heavy syntactic delimiters (such as braces, brackets, and redundant key quotes) with standard, beautiful Markdown headers and itemized lists.
+MaSON is a lightweight serialization format designed for **human-authored hierarchical documents**, **application configurations**, and **clean context-sharing for Large Language Models (LLMs)**. It replaces structural punctuation (such as curly braces, brackets, and redundant double-quoted keys) with natural Markdown headings and bulleted lists.
+
+---
+
+## 🎯 What Problem Does MaSON Solve?
+
+MaSON fits a specific niche: **human-authored hierarchical documents where visual readability and writeability are more important than representing every complex or strict academic data type.**
+
+### How it Compares:
+* **Why not JSON?** JSON is a fantastic machine-to-machine format but is tedious for humans to author or edit. Forgetting a trailing comma, double quote, or bracket results in immediate syntax errors. MaSON allows writing hierarchy naturally.
+* **Why not YAML?** YAML is powerful, but its specification is substantially more complex than MaSON's. Its indentation-sensitive syntax can also lead to subtle formatting errors when editing by hand. MaSON uses standard Markdown headings to nest structures safely.
+* **Why not TOML?** TOML is highly readable for flat structures, but its readability degrades rapidly when representing deeply nested hierarchies (requiring verbose table brackets like `[servers.database.credentials]`). MaSON utilizes standard Markdown heading depths (`#`, `##`, `###`) to establish nesting levels.
+
+---
+
+## 🎨 Design Philosophy
+
+### Design Goals
+- **Easy to read in plain text:** Looks like regular Markdown documentation.
+- **Easy to author manually:** No strict whitespace parsing, bracket-matching, or comma rules.
+- **Easy to parse:** Extremely small parser footprint (under 2KB gzipped) with a small, maintainable grammar.
+- **Deterministic & Round-trip Safe:** Standard structures parse and stringify back-and-forth cleanly.
+
+### Non-Goals
+- **Full YAML/JSON feature-parity:** No support for advanced data types or custom type tagging.
+- **Anchors, aliases, or references:** No complex object graphs or internal links.
+- **YAML-style indentation rules:** No complex multi-space layout rules. MaSON prefers simple explicit visual suffixes (`[]`) or top-level annotations over indentation-sensitive arrays.
 
 ---
 
@@ -13,9 +39,9 @@ MSON is a super-lightweight alternative to JSON/YAML/TOML designed specifically
 
 - **Zero-Bracket Nesting:** Structure child objects implicitly via standard Markdown headings (`#`, `##`, `###`).
 - **Natural Array Triggers:** Bulleted lists (`*`, `-`, `+`) automatically morph parent containers into ordered arrays.
-- **Implicit Type Casting:** Native scanning of numbers, floats, booleans (`true`/`false`), and `null` values without tedious string conversions.
-- **LLM-Token Friendly:** Eliminates redundant nested syntax, resulting in massive prompt and response cost reductions when feeding data to Gemini, GPT, or Claude.
-- **Bi-directional Integrity:** Safely stringifies complex objects back to MSON, complete with sorted parameters and beautiful spaced structure.
+- **Implicit Type Inference:** Native detection of numbers, floats, booleans (`true`/`false`), and `null` values without tedious string conversions.
+- **Grounded Token Efficiency:** In nested configuration files and content-rich documents, MaSON can reduce raw characters compared to equivalent JSON by eliminating repeated brackets, braces, and quotation marks. This is especially useful in LLM workflows, where concise representations can help maximize available context and minimize token overhead.
+- **Bi-directional Integrity:** Safely stringifies standard JavaScript objects back to MaSON, complete with sorted parameters and clean spacing.
 
 ---
 
@@ -52,7 +78,7 @@ host: localhost
 * BackupNode2
 ```
 
-### 2. Parse MSON into JSON
+### 2. Parse MaSON into JSON
 ```typescript
 import { parse } from 'mason-parser';
 import fs from 'fs';
@@ -86,7 +112,7 @@ console.log(data);
 */
 ```
 
-### 3. Stringify back to MSON
+### 3. Stringify back to MaSON
 ```typescript
 import { stringify } from 'mason-parser';
 
@@ -112,14 +138,91 @@ active: true
 
 ## 📜 Grammar & Formatting Rules
 
-1. **Parameters:** Represented by `key: value` pairs. Value is implicitly parsed as a primitive (`number`, `boolean`, `null`, or `string`).
-2. **Quoting:** To force any numerical sequence or boolean value to stay a string, simply wrap it in quotes: `zipCode: "16801"`.
+At a high level, a MaSON document is parsed line-by-line using a small, deterministic grammar.
+
+```text
+Document
+ ├── Line (Comment / Empty)    -> Ignored
+ ├── Line (Top-Level Array: []) -> Initializes the document as an anonymous Array
+ ├── Line (Heading: #+)        -> Opens a nested Object or Object within an Array
+ ├── Line (Bullet: *, -, +)    -> Pushes a primitive value to an active array
+ └── Line (Property: k: v)     -> Sets a property on the active container
+```
+
+1. **Parameters:** Represented by `key: value` pairs. The value is implicitly parsed as a primitive (`number`, `boolean`, `null`, or `string`).
+2. **Quoting:** To force any numerical sequence or boolean value to remain a string, wrap it in double or single quotes: `zipCode: "16801"`.
 3. **Headings:**
    - Any property before the first `#` is declared at the root level.
    - `#` headings denote level 1 object parameters.
    - `##` headings nest themselves inside the active `#` parent object.
-   - If there is no active `#` heading, `##` headings fall back to root.
-4. **Lists:** Bullet elements (`*`, `-`, `+`) immediately turn the nearest active heading key into an ordered array of typed primitives or objects.
+   - If there is no active parent at the required depth, headings fall back to root or nearest sibling.
+4. **Lists:** Bullet elements (`*`, `-`, `+`) immediately convert the nearest active heading key into an ordered array of typed primitives.
+5. **Explicit Array Suffix (`[]`):** To define an array of complex objects, append `[]` to the heading name (e.g., `# Users[]`). Any nested heading under it (e.g. `## User` or `##`) pushes a new object into that array.
+6. **Top-Level Anonymous Arrays:** To make the entire document parse as a top-level array, define `[]` on the very first non-empty line of the file. Each subsequent item header (like `##`) directly pushes a new anonymous object into this array.
+7. **Anonymous & Descriptive Heading Labels:** When defining elements of an array (explicit or top-level), heading names are fully optional. You can use empty heading lines (e.g., `## ` or `##`) or descriptive notes (e.g., `## Alice (Admin)`) without affecting the structured JSON properties.
+8. **Multiline Values:** Wrap any multi-line text block or formatted string in backticks (`` ` ``). The parser will automatically preserve formatting and newlines within the block.
+
+---
+
+## 🔍 Edge-Case Specification
+
+To ensure predictable behavior, `mason-parser` handles edge cases according to the following rules:
+
+### 1. Duplicate Headings
+```markdown
+# User
+name: Alice
+
+# User
+name: Bob
+```
+* **Behavior:** Overwrites. The second `# User` initializes a fresh object under the `User` key, overwriting the first one. To represent list-like collections, use bullet points under a single heading instead.
+
+### 2. Mixed-Type Arrays
+```markdown
+# Items
+* 1
+* true
+* hello
+```
+* **Behavior:** Allowed. Bullets are parsed individually. The parser yields `[1, true, "hello"]`.
+
+### 3. Arrays of Objects
+* **Behavior:** MaSON supports arrays of complex objects using the explicit array suffix (`[]`) or a top-level array modifier (`[]`). Inside these arrays, heading names can be customized with descriptive labels or left completely empty (anonymous objects). For example:
+  ```markdown
+  # Users[]
+
+  ## Administrator
+  name: Alice
+  role: admin
+
+  ##
+  name: Bob
+  role: user
+  ```
+  This parses directly into an array containing both objects under the key `"Users"`.
+
+### 4. Empty Headings
+```markdown
+# Settings
+```
+* **Behavior:** Resolves to `{}`. Encountering a heading immediately instantiates an empty object placeholder in the parent node.
+
+### 5. Backtick Delimiters (Matching)
+MaSON handles backticks dynamically based on matching the count of opening and closing backticks:
+* **Matching Delimiters & Language Tags:** A block or string starts with any count of backticks `N` (e.g. `1` backtick or `3` backticks) and ends with exactly `N` backticks. The surrounding delimiters on both ends are completely stripped.
+  * **Language Tag Stripping:** If opening with 3 or more backticks (e.g. ```` ```javascript ````), a single alphanumeric language identifier following the backticks is automatically stripped to enable seamless Markdown copying.
+  ```markdown
+  script: ```javascript
+  function calculateTotal() {}
+  ```
+  ```
+  * **Behavior:** Resolves to `"function calculateTotal() {}"`.
+* **Embedding Backticks:** By using `N` backticks as the delimiter, you can easily embed backticks of other lengths (such as code spans of length `1`) without them being treated as delimiters.
+  ```markdown
+  literalText: `` `code` ``
+  ```
+  * **Behavior:** Resolves to `"`code`"`.
 
 ---
 

package/dist/index.d.mts

@@ -24,11 +24,21 @@ interface ParseResult {
         tokenSavingsPercent: number;
     };
 }
+interface ParseOptions {
+    noTrace?: boolean;
+}
 /**
  * Casts a string value to its implicit primitive type or returns the string.
- * Strips quotes if they enclose the string explicitly.
+ * Strips quotes if they enclose the string explicitly and restores escaped characters.
  */
 declare function parsePrimitiveValue(val: string): any;
+/**
+ * Parses a single-line or multiline value, advancing the line reader index if needed.
+ */
+declare function parseValueWithMultiline(initialValStr: string, lines: string[], currentLineIndex: number): {
+    value: any;
+    nextLineIndex: number;
+};
 /**
  * Formats a value for MSON stringification.
  * Wraps in quotes if it has special characters or looks like a keyword but is a string.
@@ -37,14 +47,18 @@ declare function stringifyPrimitiveValue(val: any): string;
 /**
  * Parses MSON text into a JavaScript Object / Array.
  */
-declare function parse(text: string): any;
+declare function parse(text: string, options?: ParseOptions): any;
+/**
+ * Ultra-performance, trace-free parser for MSON.
+ */
+declare function fastParseWithTrace(text: string): ParseResult;
 /**
  * Parses MSON text into a JavaScript Object / Array with step-by-step trace info.
  */
-declare function parseWithTrace(text: string): ParseResult;
+declare function parseWithTrace(text: string, options?: ParseOptions): ParseResult;
 /**
  * Stringifies a JavaScript object/array back into MSON text recursively.
  */
-declare function stringify(obj: any, level?: number): string;
+declare function stringify(obj: any, level?: number, parentKey?: string): string;
 
-export { type ParseResult, type ParserTraceStep, parse, parse as parseMSON, parsePrimitiveValue, parseWithTrace, stringify, stringify as stringifyMSON, stringifyPrimitiveValue };
+export { type ParseOptions, type ParseResult, type ParserTraceStep, fastParseWithTrace, parse, parse as parseMSON, parseWithTrace as parseMaSON, parsePrimitiveValue, parseValueWithMultiline, parseWithTrace, stringify, stringify as stringifyMSON, stringify as stringifyMaSON, stringifyPrimitiveValue };

package/dist/index.d.ts

@@ -24,11 +24,21 @@ interface ParseResult {
         tokenSavingsPercent: number;
     };
 }
+interface ParseOptions {
+    noTrace?: boolean;
+}
 /**
  * Casts a string value to its implicit primitive type or returns the string.
- * Strips quotes if they enclose the string explicitly.
+ * Strips quotes if they enclose the string explicitly and restores escaped characters.
  */
 declare function parsePrimitiveValue(val: string): any;
+/**
+ * Parses a single-line or multiline value, advancing the line reader index if needed.
+ */
+declare function parseValueWithMultiline(initialValStr: string, lines: string[], currentLineIndex: number): {
+    value: any;
+    nextLineIndex: number;
+};
 /**
  * Formats a value for MSON stringification.
  * Wraps in quotes if it has special characters or looks like a keyword but is a string.
@@ -37,14 +47,18 @@ declare function stringifyPrimitiveValue(val: any): string;
 /**
  * Parses MSON text into a JavaScript Object / Array.
  */
-declare function parse(text: string): any;
+declare function parse(text: string, options?: ParseOptions): any;
+/**
+ * Ultra-performance, trace-free parser for MSON.
+ */
+declare function fastParseWithTrace(text: string): ParseResult;
 /**
  * Parses MSON text into a JavaScript Object / Array with step-by-step trace info.
  */
-declare function parseWithTrace(text: string): ParseResult;
+declare function parseWithTrace(text: string, options?: ParseOptions): ParseResult;
 /**
  * Stringifies a JavaScript object/array back into MSON text recursively.
  */
-declare function stringify(obj: any, level?: number): string;
+declare function stringify(obj: any, level?: number, parentKey?: string): string;
 
-export { type ParseResult, type ParserTraceStep, parse, parse as parseMSON, parsePrimitiveValue, parseWithTrace, stringify, stringify as stringifyMSON, stringifyPrimitiveValue };
+export { type ParseOptions, type ParseResult, type ParserTraceStep, fastParseWithTrace, parse, parse as parseMSON, parseWithTrace as parseMaSON, parsePrimitiveValue, parseValueWithMultiline, parseWithTrace, stringify, stringify as stringifyMSON, stringify as stringifyMaSON, stringifyPrimitiveValue };