mason-parser 1.0.0 → 1.0.1

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,84 @@ 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.
+
+---
+
+## 🔍 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. Escaping Special Characters
+* To include colons or other special symbols in a string value, wrap the value in double quotes:
+  ```markdown
+  title: "Hello: World"
+  ```
+* To represent a literal markdown header symbol inside a string value, wrap it:
+  ```markdown
+  banner: "# Welcome To My Server"
+  ```
 
 ---
 

package/dist/index.d.mts

@@ -45,6 +45,6 @@ declare function parseWithTrace(text: string): 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 };

package/dist/index.d.ts

@@ -45,6 +45,6 @@ declare function parseWithTrace(text: string): 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 };

package/dist/index.js

@@ -60,7 +60,8 @@ function parseWithTrace(text) {
   const startTime = typeof performance !== "undefined" ? performance.now() : Date.now();
   const lines = text.split(/\r?\n/);
   const trace = [];
-  const root = {};
+  let root = {};
+  let rootConvertedToArray = false;
   const stack = [];
   const getStackNames = () => stack.map((s) => `${"#".repeat(s.level)} ${s.key}`);
   for (let i = 0; i < lines.length; i++) {
@@ -78,47 +79,95 @@ function parseWithTrace(text) {
       });
       continue;
     }
+    if (line === "[]") {
+      const isRootEmpty = Array.isArray(root) ? root.length === 0 : Object.keys(root).length === 0;
+      if (stack.length === 0 && !rootConvertedToArray && isRootEmpty) {
+        root = [];
+        rootConvertedToArray = true;
+        trace.push({
+          lineNumber,
+          lineText: rawLine,
+          action: 'Converted root container to an Array via top-level "[]"',
+          stackDepth: stack.length,
+          currentStack: getStackNames(),
+          status: "success"
+        });
+        continue;
+      }
+    }
     if (line.startsWith("#")) {
       const headingMatch = line.match(/^(#+)\s*(.*)$/);
       if (headingMatch) {
         const hashCount = headingMatch[1].length;
-        const headingName = headingMatch[2].trim();
-        if (!headingName) {
-          trace.push({
-            lineNumber,
-            lineText: rawLine,
-            action: `Warning: Empty heading name at level ${hashCount}`,
-            stackDepth: stack.length,
-            currentStack: getStackNames(),
-            status: "warning"
-          });
-          continue;
-        }
+        let headingName = headingMatch[2].trim();
         while (stack.length > 0 && stack[stack.length - 1].level >= hashCount) {
           stack.pop();
         }
         let activeParent = root;
+        let activeParentItem = null;
         if (stack.length > 0) {
-          const topItem = stack[stack.length - 1];
-          activeParent = topItem.value;
+          activeParentItem = stack[stack.length - 1];
+          activeParent = activeParentItem.value;
         }
-        const newNode = {};
-        if (Array.isArray(activeParent)) {
-          activeParent.push({ [headingName]: newNode });
+        if (!headingName) {
+          if (activeParentItem && activeParentItem.isExplicitArray || Array.isArray(activeParent)) {
+            headingName = "";
+          } else {
+            trace.push({
+              lineNumber,
+              lineText: rawLine,
+              action: `Warning: Empty heading name at level ${hashCount}`,
+              stackDepth: stack.length,
+              currentStack: getStackNames(),
+              status: "warning"
+            });
+            continue;
+          }
+        }
+        let isExplicitArray = false;
+        if (headingName.endsWith("[]")) {
+          headingName = headingName.slice(0, -2).trim();
+          isExplicitArray = true;
+        }
+        const newNode = isExplicitArray ? [] : {};
+        if (activeParentItem && activeParentItem.isExplicitArray) {
+          activeParent.push(newNode);
           trace.push({
             lineNumber,
             lineText: rawLine,
-            action: `Created heading "${headingName}" at level ${hashCount} and pushed inside parent Array`,
+            action: `Pushed new item into explicit array "${activeParentItem.key}" via heading "${headingName}"`,
             stackDepth: stack.length,
             currentStack: getStackNames(),
             status: "success"
           });
+        } else if (Array.isArray(activeParent)) {
+          if (headingName === "") {
+            activeParent.push(newNode);
+            trace.push({
+              lineNumber,
+              lineText: rawLine,
+              action: `Pushed anonymous object directly into parent Array`,
+              stackDepth: stack.length,
+              currentStack: getStackNames(),
+              status: "success"
+            });
+          } else {
+            activeParent.push({ [headingName]: newNode });
+            trace.push({
+              lineNumber,
+              lineText: rawLine,
+              action: `Created heading "${headingName}" at level ${hashCount} and pushed inside parent Array`,
+              stackDepth: stack.length,
+              currentStack: getStackNames(),
+              status: "success"
+            });
+          }
         } else {
           activeParent[headingName] = newNode;
           trace.push({
             lineNumber,
             lineText: rawLine,
-            action: `Created heading "${headingName}" at level ${hashCount} in parent Object`,
+            action: `Created heading "${headingName}" at level ${hashCount} in parent Object${isExplicitArray ? " as Array" : ""}`,
             stackDepth: stack.length,
             currentStack: getStackNames(),
             status: "success"
@@ -129,7 +178,8 @@ function parseWithTrace(text) {
           key: headingName,
           parent: activeParent,
           value: newNode,
-          type: "object"
+          type: isExplicitArray ? "array" : "object",
+          isExplicitArray
         });
         continue;
       }
@@ -255,14 +305,35 @@ function parseWithTrace(text) {
     }
   };
 }
-function stringify(obj, level = 0) {
+function stringify(obj, level = 0, parentKey) {
   if (obj === null || obj === void 0) return "";
   let output = "";
   const hashes = (lvl) => "#".repeat(lvl);
   if (Array.isArray(obj)) {
+    if (level === 0) {
+      output += "[]\n\n";
+    }
+    let itemName = "Item";
+    if (parentKey) {
+      if (parentKey.endsWith("ies")) {
+        itemName = parentKey.slice(0, -3) + "y";
+      } else if (parentKey.endsWith("s") && !parentKey.endsWith("ss")) {
+        itemName = parentKey.slice(0, -1);
+      } else {
+        itemName = parentKey;
+      }
+      itemName = itemName.charAt(0).toUpperCase() + itemName.slice(1);
+    }
     for (const item of obj) {
       if (typeof item === "object" && item !== null) {
-        output += stringify(item, level);
+        const nextLevel = level + 1;
+        output += `${hashes(nextLevel)} ${itemName}
+`;
+        const nestedString = stringify(item, nextLevel);
+        if (nestedString) {
+          output += nestedString;
+        }
+        output += "\n";
       } else {
         output += `* ${stringifyPrimitiveValue(item)}
 `;
@@ -281,10 +352,12 @@ function stringify(obj, level = 0) {
     }
     for (const key of complex) {
       const nextLevel = level + 1;
-      output += `${hashes(nextLevel)} ${key}
-`;
       const val = obj[key];
-      const nestedString = stringify(val, nextLevel);
+      const isArrayOfObjects = Array.isArray(val) && val.some((item) => typeof item === "object" && item !== null);
+      const headingNameSuffix = isArrayOfObjects ? "[]" : "";
+      output += `${hashes(nextLevel)} ${key}${headingNameSuffix}
+`;
+      const nestedString = stringify(val, nextLevel, key);
       if (nestedString) {
         output += nestedString;
       }

package/dist/index.mjs

@@ -30,7 +30,8 @@ function parseWithTrace(text) {
   const startTime = typeof performance !== "undefined" ? performance.now() : Date.now();
   const lines = text.split(/\r?\n/);
   const trace = [];
-  const root = {};
+  let root = {};
+  let rootConvertedToArray = false;
   const stack = [];
   const getStackNames = () => stack.map((s) => `${"#".repeat(s.level)} ${s.key}`);
   for (let i = 0; i < lines.length; i++) {
@@ -48,47 +49,95 @@ function parseWithTrace(text) {
       });
       continue;
     }
+    if (line === "[]") {
+      const isRootEmpty = Array.isArray(root) ? root.length === 0 : Object.keys(root).length === 0;
+      if (stack.length === 0 && !rootConvertedToArray && isRootEmpty) {
+        root = [];
+        rootConvertedToArray = true;
+        trace.push({
+          lineNumber,
+          lineText: rawLine,
+          action: 'Converted root container to an Array via top-level "[]"',
+          stackDepth: stack.length,
+          currentStack: getStackNames(),
+          status: "success"
+        });
+        continue;
+      }
+    }
     if (line.startsWith("#")) {
       const headingMatch = line.match(/^(#+)\s*(.*)$/);
       if (headingMatch) {
         const hashCount = headingMatch[1].length;
-        const headingName = headingMatch[2].trim();
-        if (!headingName) {
-          trace.push({
-            lineNumber,
-            lineText: rawLine,
-            action: `Warning: Empty heading name at level ${hashCount}`,
-            stackDepth: stack.length,
-            currentStack: getStackNames(),
-            status: "warning"
-          });
-          continue;
-        }
+        let headingName = headingMatch[2].trim();
         while (stack.length > 0 && stack[stack.length - 1].level >= hashCount) {
           stack.pop();
         }
         let activeParent = root;
+        let activeParentItem = null;
         if (stack.length > 0) {
-          const topItem = stack[stack.length - 1];
-          activeParent = topItem.value;
+          activeParentItem = stack[stack.length - 1];
+          activeParent = activeParentItem.value;
         }
-        const newNode = {};
-        if (Array.isArray(activeParent)) {
-          activeParent.push({ [headingName]: newNode });
+        if (!headingName) {
+          if (activeParentItem && activeParentItem.isExplicitArray || Array.isArray(activeParent)) {
+            headingName = "";
+          } else {
+            trace.push({
+              lineNumber,
+              lineText: rawLine,
+              action: `Warning: Empty heading name at level ${hashCount}`,
+              stackDepth: stack.length,
+              currentStack: getStackNames(),
+              status: "warning"
+            });
+            continue;
+          }
+        }
+        let isExplicitArray = false;
+        if (headingName.endsWith("[]")) {
+          headingName = headingName.slice(0, -2).trim();
+          isExplicitArray = true;
+        }
+        const newNode = isExplicitArray ? [] : {};
+        if (activeParentItem && activeParentItem.isExplicitArray) {
+          activeParent.push(newNode);
           trace.push({
             lineNumber,
             lineText: rawLine,
-            action: `Created heading "${headingName}" at level ${hashCount} and pushed inside parent Array`,
+            action: `Pushed new item into explicit array "${activeParentItem.key}" via heading "${headingName}"`,
             stackDepth: stack.length,
             currentStack: getStackNames(),
             status: "success"
           });
+        } else if (Array.isArray(activeParent)) {
+          if (headingName === "") {
+            activeParent.push(newNode);
+            trace.push({
+              lineNumber,
+              lineText: rawLine,
+              action: `Pushed anonymous object directly into parent Array`,
+              stackDepth: stack.length,
+              currentStack: getStackNames(),
+              status: "success"
+            });
+          } else {
+            activeParent.push({ [headingName]: newNode });
+            trace.push({
+              lineNumber,
+              lineText: rawLine,
+              action: `Created heading "${headingName}" at level ${hashCount} and pushed inside parent Array`,
+              stackDepth: stack.length,
+              currentStack: getStackNames(),
+              status: "success"
+            });
+          }
         } else {
           activeParent[headingName] = newNode;
           trace.push({
             lineNumber,
             lineText: rawLine,
-            action: `Created heading "${headingName}" at level ${hashCount} in parent Object`,
+            action: `Created heading "${headingName}" at level ${hashCount} in parent Object${isExplicitArray ? " as Array" : ""}`,
             stackDepth: stack.length,
             currentStack: getStackNames(),
             status: "success"
@@ -99,7 +148,8 @@ function parseWithTrace(text) {
           key: headingName,
           parent: activeParent,
           value: newNode,
-          type: "object"
+          type: isExplicitArray ? "array" : "object",
+          isExplicitArray
         });
         continue;
       }
@@ -225,14 +275,35 @@ function parseWithTrace(text) {
     }
   };
 }
-function stringify(obj, level = 0) {
+function stringify(obj, level = 0, parentKey) {
   if (obj === null || obj === void 0) return "";
   let output = "";
   const hashes = (lvl) => "#".repeat(lvl);
   if (Array.isArray(obj)) {
+    if (level === 0) {
+      output += "[]\n\n";
+    }
+    let itemName = "Item";
+    if (parentKey) {
+      if (parentKey.endsWith("ies")) {
+        itemName = parentKey.slice(0, -3) + "y";
+      } else if (parentKey.endsWith("s") && !parentKey.endsWith("ss")) {
+        itemName = parentKey.slice(0, -1);
+      } else {
+        itemName = parentKey;
+      }
+      itemName = itemName.charAt(0).toUpperCase() + itemName.slice(1);
+    }
     for (const item of obj) {
       if (typeof item === "object" && item !== null) {
-        output += stringify(item, level);
+        const nextLevel = level + 1;
+        output += `${hashes(nextLevel)} ${itemName}
+`;
+        const nestedString = stringify(item, nextLevel);
+        if (nestedString) {
+          output += nestedString;
+        }
+        output += "\n";
       } else {
         output += `* ${stringifyPrimitiveValue(item)}
 `;
@@ -251,10 +322,12 @@ function stringify(obj, level = 0) {
     }
     for (const key of complex) {
       const nextLevel = level + 1;
-      output += `${hashes(nextLevel)} ${key}
-`;
       const val = obj[key];
-      const nestedString = stringify(val, nextLevel);
+      const isArrayOfObjects = Array.isArray(val) && val.some((item) => typeof item === "object" && item !== null);
+      const headingNameSuffix = isArrayOfObjects ? "[]" : "";
+      output += `${hashes(nextLevel)} ${key}${headingNameSuffix}
+`;
+      const nestedString = stringify(val, nextLevel, key);
       if (nestedString) {
         output += nestedString;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mason-parser",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A lightweight, high-performance Markdown Structured Object Notation (MSON) parser and stringifier.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",