links-notation 0.11.2 → 0.12.0

package/src/Link.js

@@ -1,43 +1,92 @@
 export class Link {
+  /**
+   * Create a new Link
+   * @param {string|null} id - Optional identifier for the link
+   * @param {Link[]|null} values - Optional array of nested links
+   * @throws {TypeError} If values is not an array or null
+   */
   constructor(id = null, values = null) {
     this.id = id;
-    this.values = values || [];
+
+    // Validate that values is an array if provided
+    if (values !== null && values !== undefined) {
+      if (!Array.isArray(values)) {
+        throw new TypeError('values must be an array or null');
+      }
+      this.values = values;
+    } else {
+      this.values = [];
+    }
   }
 
+  /**
+   * Convert link to string representation
+   * @returns {string} String representation of the link
+   */
   toString() {
     return this.format(false);
   }
 
+  /**
+   * Get formatted string of all values
+   * @returns {string} Space-separated string of values
+   */
   getValuesString() {
-    return (!this.values || this.values.length === 0) ? 
+    return (!this.values || this.values.length === 0) ?
       '' : this.values.map(v => Link.getValueString(v)).join(' ');
   }
 
+  /**
+   * Simplify the link structure by unwrapping single-value containers
+   * @returns {Link} Simplified link
+   */
   simplify() {
     if (!this.values || this.values.length === 0) {
       return this;
     } else if (this.values.length === 1) {
       return this.values[0];
     } else {
-      const newValues = this.values.map(v => v.simplify());
+      const newValues = this.values.map(v => {
+        // Check if value has simplify method (defensive programming)
+        return v && typeof v.simplify === 'function' ? v.simplify() : v;
+      });
       return new Link(this.id, newValues);
     }
   }
 
+  /**
+   * Combine this link with another link
+   * @param {Link} other - The link to combine with
+   * @returns {Link} Combined link
+   */
   combine(other) {
     return new Link(null, [this, other]);
   }
 
+  /**
+   * Get string representation of a value
+   * @param {Link} value - The value to stringify
+   * @returns {string} String representation
+   */
   static getValueString(value) {
-    return value.toLinkOrIdString();
+    // Defensive check for method existence
+    return value && typeof value.toLinkOrIdString === 'function' ? value.toLinkOrIdString() : String(value);
   }
 
+  /**
+   * Escape a reference string by adding quotes if necessary
+   * @param {string} reference - The reference to escape
+   * @returns {string} Escaped reference
+   */
   static escapeReference(reference) {
     if (!reference || reference.trim() === '') {
       return '';
     }
-    
-    const needsSingleQuotes = 
+
+    const hasSingleQuote = reference.includes("'");
+    const hasDoubleQuote = reference.includes('"');
+
+    const needsQuoting =
       reference.includes(':') ||
       reference.includes('(') ||
       reference.includes(')') ||
@@ -45,17 +94,38 @@ export class Link {
       reference.includes('\t') ||
       reference.includes('\n') ||
       reference.includes('\r') ||
-      reference.includes('"');
-    
-    if (needsSingleQuotes) {
+      hasDoubleQuote ||
+      hasSingleQuote;
+
+    // Handle edge case: reference contains both single and double quotes
+    if (hasSingleQuote && hasDoubleQuote) {
+      // Escape single quotes and wrap in single quotes
+      return `'${reference.replace(/'/g, "\\'")}'`;
+    }
+
+    // Prefer single quotes if double quotes are present
+    if (hasDoubleQuote) {
       return `'${reference}'`;
-    } else if (reference.includes("'")) {
+    }
+
+    // Use double quotes if single quotes are present
+    if (hasSingleQuote) {
       return `"${reference}"`;
-    } else {
-      return reference;
     }
+
+    // Use single quotes for special characters
+    if (needsQuoting) {
+      return `'${reference}'`;
+    }
+
+    // No quoting needed
+    return reference;
   }
 
+  /**
+   * Convert to string using either just ID or full format
+   * @returns {string} String representation
+   */
   toLinkOrIdString() {
     if (!this.values || this.values.length === 0) {
       return this.id === null ? '' : Link.escapeReference(this.id);
@@ -63,21 +133,53 @@ export class Link {
     return this.toString();
   }
 
+  /**
+   * Check equality with another Link
+   * @param {*} other - Object to compare with
+   * @returns {boolean} True if links are equal
+   */
   equals(other) {
     if (!(other instanceof Link)) return false;
     if (this.id !== other.id) return false;
-    if (this.values.length !== other.values.length) return false;
-    
-    for (let i = 0; i < this.values.length; i++) {
-      if (!this.values[i].equals(other.values[i])) {
-        return false;
+
+    // Handle null/undefined values arrays
+    const thisValues = this.values || [];
+    const otherValues = other.values || [];
+
+    if (thisValues.length !== otherValues.length) return false;
+
+    for (let i = 0; i < thisValues.length; i++) {
+      // Defensive check for equals method
+      if (thisValues[i] && typeof thisValues[i].equals === 'function') {
+        if (!thisValues[i].equals(otherValues[i])) {
+          return false;
+        }
+      } else {
+        // Fallback to reference equality
+        if (thisValues[i] !== otherValues[i]) {
+          return false;
+        }
       }
     }
     return true;
   }
 
-  
+
+  /**
+   * Format the link as a string
+   * @param {boolean|FormatOptions} lessParentheses - If true, omit parentheses where safe; or a FormatOptions object
+   * @param {boolean} isCompoundValue - If true, this is a value in a compound link
+   * @returns {string} Formatted string
+   */
   format(lessParentheses = false, isCompoundValue = false) {
+    // Support FormatOptions/FormatConfig as first parameter
+    // Check if it's an object with formatting properties (FormatOptions or FormatConfig)
+    if (lessParentheses && typeof lessParentheses === 'object' &&
+        (lessParentheses.constructor.name === 'FormatOptions' || lessParentheses.constructor.name === 'FormatConfig')) {
+      return this._formatWithOptions(lessParentheses, isCompoundValue);
+    }
+
+    // Original implementation for backward compatibility
     // Empty link
     if (this.id === null && (!this.values || this.values.length === 0)) {
       return lessParentheses ? '' : '()';
@@ -121,35 +223,195 @@ export class Link {
     return lessParentheses && !this.needsParentheses(this.id) ? withColon : `(${withColon})`;
   }
   
+  /**
+   * Format a value within this link
+   * @param {Link} value - The value to format
+   * @returns {string} Formatted value string
+   */
   formatValue(value) {
-    if (!value.format) {
-      return Link.escapeReference(value.id || '');
+    if (!value || !value.format) {
+      return Link.escapeReference((value && value.id) || '');
     }
-    
+
     // Check if we're in a compound link that was created from path combinations
     // This is indicated by having a parent context passed through
     const isCompoundFromPaths = this._isFromPathCombination === true;
-    
+
     // For compound links from paths, format values with parentheses
     if (isCompoundFromPaths) {
       return value.format(false, true);
     }
-    
+
     // Simple link with just an ID - don't wrap in parentheses when used as a value
     if (!value.values || value.values.length === 0) {
       return Link.escapeReference(value.id);
     }
-    
+
     // Complex value with its own structure - format it normally with parentheses
     return value.format(false, false);
   }
-  
+
+  /**
+   * Check if a string needs to be wrapped in parentheses
+   * @param {string} str - The string to check
+   * @returns {boolean} True if parentheses are needed
+   */
   needsParentheses(str) {
     return str && (str.includes(' ') || str.includes(':') || str.includes('(') || str.includes(')'));
   }
+
+  /**
+   * Format the link using a FormatOptions object
+   * @param {FormatOptions} options - FormatOptions object with formatting options
+   * @param {boolean} isCompoundValue - If true, this is a value in a compound link
+   * @returns {string} Formatted string
+   */
+  _formatWithOptions(options, isCompoundValue = false) {
+    // Empty link
+    if (this.id === null && (!this.values || this.values.length === 0)) {
+      return options.lessParentheses ? '' : '()';
+    }
+
+    // Link with only ID, no values
+    if (!this.values || this.values.length === 0) {
+      const escapedId = Link.escapeReference(this.id);
+      if (isCompoundValue) {
+        return `(${escapedId})`;
+      }
+      return options.lessParentheses && !this.needsParentheses(this.id) ? escapedId : `(${escapedId})`;
+    }
+
+    // Check if we should use indented format
+    let shouldIndent = false;
+    if (options.shouldIndentByRefCount(this.values.length)) {
+      shouldIndent = true;
+    } else {
+      // Try inline format first
+      const valuesStr = this.values.map(v => this.formatValue(v)).join(' ');
+      let testLine;
+      if (this.id !== null) {
+        const idStr = Link.escapeReference(this.id);
+        testLine = options.lessParentheses ? `${idStr}: ${valuesStr}` : `(${idStr}: ${valuesStr})`;
+      } else {
+        testLine = options.lessParentheses ? valuesStr : `(${valuesStr})`;
+      }
+
+      if (options.shouldIndentByLength(testLine)) {
+        shouldIndent = true;
+      }
+    }
+
+    // Format with indentation if needed
+    if (shouldIndent && options.preferInline === false) {
+      return this._formatIndented(options);
+    }
+
+    // Standard inline formatting
+    const valuesStr = this.values.map(v => this.formatValue(v)).join(' ');
+
+    // Link with values only (null id)
+    if (this.id === null) {
+      if (options.lessParentheses) {
+        const allSimple = this.values.every(v => !v.values || v.values.length === 0);
+        if (allSimple) {
+          return this.values.map(v => Link.escapeReference(v.id)).join(' ');
+        }
+        return valuesStr;
+      }
+      return `(${valuesStr})`;
+    }
+
+    // Link with ID and values
+    const idStr = Link.escapeReference(this.id);
+    const withColon = `${idStr}: ${valuesStr}`;
+    return options.lessParentheses && !this.needsParentheses(this.id) ? withColon : `(${withColon})`;
+  }
+
+  /**
+   * Format the link with indentation
+   * @param {FormatOptions} options - FormatOptions object with formatting options
+   * @returns {string} Indented formatted string
+   */
+  _formatIndented(options) {
+    if (this.id === null) {
+      // Values only - format each on separate line
+      const lines = this.values.map(v => options.indentString + this.formatValue(v));
+      return lines.join('\n');
+    }
+
+    // Link with ID - format as id:\n  value1\n  value2
+    const idStr = Link.escapeReference(this.id);
+    const lines = [`${idStr}:`];
+    for (const v of this.values) {
+      lines.push(options.indentString + this.formatValue(v));
+    }
+    return lines.join('\n');
+  }
+}
+
+/**
+ * Group consecutive links with the same ID
+ * @param {Link[]} links - List of links to group
+ * @returns {Link[]} New list with consecutive links grouped
+ */
+function _groupConsecutiveLinks(links) {
+  if (!links || links.length === 0) {
+    return links;
+  }
+
+  const grouped = [];
+  let i = 0;
+
+  while (i < links.length) {
+    const current = links[i];
+
+    // Look ahead for consecutive links with same ID
+    if (current.id !== null && current.values && current.values.length > 0) {
+      // Collect all values with same ID
+      const sameIdValues = [...current.values];
+      let j = i + 1;
+
+      while (j < links.length) {
+        const nextLink = links[j];
+        if (nextLink.id === current.id && nextLink.values && nextLink.values.length > 0) {
+          sameIdValues.push(...nextLink.values);
+          j++;
+        } else {
+          break;
+        }
+      }
+
+      // If we found consecutive links, create grouped link
+      if (j > i + 1) {
+        const groupedLink = new Link(current.id, sameIdValues);
+        grouped.push(groupedLink);
+        i = j;
+        continue;
+      }
+    }
+
+    grouped.push(current);
+    i++;
+  }
+
+  return grouped;
 }
 
 export function formatLinks(links, lessParentheses = false) {
   if (!links || links.length === 0) return '';
+
+  // Support FormatOptions/FormatConfig as parameter
+  if (lessParentheses && typeof lessParentheses === 'object' &&
+      (lessParentheses.constructor.name === 'FormatOptions' || lessParentheses.constructor.name === 'FormatConfig')) {
+    const options = lessParentheses;
+    // Apply consecutive link grouping if enabled
+    let linksToFormat = links;
+    if (options.groupConsecutive) {
+      linksToFormat = _groupConsecutiveLinks(links);
+    }
+    return linksToFormat.map(link => link.format(options)).join('\n');
+  }
+
+  // Backward compatibility with boolean parameter
   return links.map(link => link.format(lessParentheses)).join('\n');
 }

package/src/Parser.js

@@ -2,24 +2,52 @@ import { Link } from './Link.js';
 import * as parserModule from './parser-generated.js';
 
 export class Parser {
-  constructor() {
+  /**
+   * Create a new Parser instance
+   * @param {Object} options - Parser options
+   * @param {number} options.maxInputSize - Maximum input size in bytes (default: 10MB)
+   * @param {number} options.maxDepth - Maximum nesting depth (default: 1000)
+   */
+  constructor(options = {}) {
+    this.maxInputSize = options.maxInputSize || 10 * 1024 * 1024; // 10MB default
+    this.maxDepth = options.maxDepth || 1000;
   }
 
+  /**
+   * Parse Lino notation text into Link objects
+   * @param {string} input - The Lino notation text to parse
+   * @returns {Link[]} Array of parsed Link objects
+   * @throws {Error} If parsing fails
+   */
   parse(input) {
+    // Validate input
+    if (typeof input !== 'string') {
+      throw new TypeError('Input must be a string');
+    }
+
+    if (input.length > this.maxInputSize) {
+      throw new Error(`Input size exceeds maximum allowed size of ${this.maxInputSize} bytes`);
+    }
+
     try {
       const rawResult = parserModule.parse(input);
       return this.transformResult(rawResult);
     } catch (error) {
-      throw new Error(`Parse error: ${error.message}`);
+      // Preserve original error information
+      const parseError = new Error(`Parse error: ${error.message}`);
+      parseError.cause = error;
+      parseError.location = error.location;
+      throw parseError;
     }
   }
 
   transformResult(rawResult) {
     const links = [];
     const items = Array.isArray(rawResult) ? rawResult : [rawResult];
-    
+
     for (const item of items) {
-      if (item) {
+      // Use explicit null/undefined check
+      if (item !== null && item !== undefined) {
         this.collectLinks(item, [], links);
       }
     }
@@ -27,7 +55,8 @@ export class Parser {
   }
 
   collectLinks(item, parentPath, result) {
-    if (!item) return;
+    // Use explicit null/undefined check
+    if (item === null || item === undefined) return;
 
     // For items with children (indented structure)
     if (item.children && item.children.length > 0) {
@@ -105,9 +134,15 @@ export class Parser {
   }
   
 
+  /**
+   * Transform a parsed item into a Link object
+   * @param {*} item - The item to transform
+   * @returns {Link|null} The transformed Link or null
+   */
   transformLink(item) {
-    if (!item) return null;
-    
+    // Use explicit null/undefined check
+    if (item === null || item === undefined) return null;
+
     if (item instanceof Link) {
       return item;
     }
@@ -124,7 +159,7 @@ export class Parser {
       link.values = item.values.map(v => this.transformLink(v));
       return link;
     }
-    
+
     // Default case
     return new Link(item.id || null, []);
   }

package/src/index.js

@@ -1,3 +1,5 @@
 export { Link, formatLinks } from './Link.js';
 export { LinksGroup } from './LinksGroup.js';
-export { Parser } from './Parser.js';
+export { Parser } from './Parser.js';
+export { FormatConfig } from './FormatConfig.js';
+export { FormatOptions } from './FormatOptions.js';

package/tests/ApiTests.test.js

@@ -1,9 +1,25 @@
 import { test, expect } from 'bun:test';
 import { Parser } from '../src/Parser.js';
-import { Link } from '../src/Link.js';
+import { Link, formatLinks } from '../src/Link.js';
+import { FormatOptions } from '../src/FormatOptions.js';
 
 const parser = new Parser();
 
+test('test_is_ref', () => {
+  // JS doesn't have separate Ref/Link types, but we can test simple link behavior
+  const simpleLink = new Link('some_value');
+  expect(simpleLink.id).toBe('some_value');
+  expect(simpleLink.values).toEqual([]);
+});
+
+test('test_is_link', () => {
+  // Test link with values
+  const link = new Link('id', [new Link('child')]);
+  expect(link.id).toBe('id');
+  expect(link.values.length).toBe(1);
+  expect(link.values[0].id).toBe('child');
+});
+
 test('test_is_ref equivalent', () => {
   // JS doesn't have separate Ref/Link types, but we can test simple link behavior
   const simpleLink = new Link('some_value');
@@ -28,7 +44,7 @@ test('test_empty_link', () => {
 test('test_simple_link', () => {
   const input = '(1: 1 1)';
   const parsed = parser.parse(input);
-  
+
   // Validate regular formatting
   const output = parsed[0].format();
   const expected = '(1: 1 1)'; // JS format matches input
@@ -38,7 +54,7 @@ test('test_simple_link', () => {
 test('test_link_with_source_target', () => {
   const input = '(index: source target)';
   const parsed = parser.parse(input);
-  
+
   // Validate regular formatting
   const output = parsed[0].format();
   expect(output).toBe(input);
@@ -47,7 +63,7 @@ test('test_link_with_source_target', () => {
 test('test_link_with_source_type_target', () => {
   const input = '(index: source type target)';
   const parsed = parser.parse(input);
-  
+
   // Validate regular formatting
   const output = parsed[0].format();
   expect(output).toBe(input);
@@ -56,7 +72,7 @@ test('test_link_with_source_type_target', () => {
 test('test_single_line_format', () => {
   const input = 'id: value1 value2';
   const parsed = parser.parse(input);
-  
+
   // The parser should handle single-line format
   const output = parsed[0].format(true); // lessParentheses mode
   expect(output).toContain('id');
@@ -67,8 +83,89 @@ test('test_single_line_format', () => {
 test('test_quoted_references', () => {
   const input = '("quoted id": "value with spaces")';
   const parsed = parser.parse(input);
-  
+
   const output = parsed[0].format();
   expect(output).toContain('quoted id');
   expect(output).toContain('value with spaces');
-});
+});
+
+test('test_quoted_references_parsing', () => {
+  // Test that quoted references are parsed correctly
+  const input = '("quoted id": "value with spaces")';
+  const parsed = parser.parse(input);
+
+  // Verify parsing worked correctly
+  const output = formatLinks(parsed);
+  expect(output).toContain('quoted id');
+  expect(output).toContain('value with spaces');
+});
+
+test('test_indented_id_syntax_parsing', () => {
+  // Test that indented ID syntax is parsed correctly
+  const indented = `id:
+  value1
+  value2`;
+  const inline = '(id: value1 value2)';
+
+  const indentedParsed = parser.parse(indented);
+  const inlineParsed = parser.parse(inline);
+
+  // Both should produce equivalent structures
+  const indentedOutput = formatLinks(indentedParsed);
+  const inlineOutput = formatLinks(inlineParsed);
+  expect(indentedOutput).toBe(inlineOutput);
+  expect(indentedOutput).toBe('(id: value1 value2)');
+});
+
+test('test_indented_id_syntax_roundtrip', () => {
+  const input = `id:
+  value1
+  value2`;
+  const parsed = parser.parse(input);
+
+  // Validate that we can format with indented syntax using FormatOptions
+  const options = new FormatOptions();
+  options.maxInlineRefs = 1;  // Force indentation with more than 1 ref
+  options.preferInline = false;
+  const output = formatLinks(parsed, options);
+  expect(output).toBe(input);
+});
+
+test('test_multiple_indented_id_syntax_parsing', () => {
+  // Test that multiple indented ID links are parsed correctly
+  const indented = `id1:
+  a
+  b
+id2:
+  c
+  d`;
+  const inline = `(id1: a b)
+(id2: c d)`;
+
+  const indentedParsed = parser.parse(indented);
+  const inlineParsed = parser.parse(inline);
+
+  // Both should produce equivalent structures
+  const indentedOutput = formatLinks(indentedParsed);
+  const inlineOutput = formatLinks(inlineParsed);
+  expect(indentedOutput).toBe(inlineOutput);
+  expect(indentedOutput).toBe(`(id1: a b)
+(id2: c d)`);
+});
+
+test('test_multiple_indented_id_syntax_roundtrip', () => {
+  const input = `id1:
+  a
+  b
+id2:
+  c
+  d`;
+  const parsed = parser.parse(input);
+
+  // Validate that we can format with indented syntax using FormatOptions
+  const options = new FormatOptions();
+  options.maxInlineRefs = 1;  // Force indentation with more than 1 ref
+  options.preferInline = false;
+  const output = formatLinks(parsed, options);
+  expect(output).toBe(input);
+});