links-notation 0.13.0 → 0.16.0

package/examples/typescript-example.ts

@@ -0,0 +1,95 @@
+/**
+ * TypeScript example demonstrating usage of links-notation with type checking
+ */
+
+import {
+  Parser,
+  Link,
+  FormatOptions,
+  FormatConfig,
+  formatLinks,
+} from '../index.js';
+
+// Example 1: Basic parsing
+const parser = new Parser();
+const input = '(index: source target)';
+const links: Link[] = parser.parse(input);
+
+// Example 2: Creating links programmatically
+const link1 = new Link('parent', [new Link('child1'), new Link('child2')]);
+
+console.log(link1.toString());
+
+// Example 3: Working with link properties
+const link2 = new Link('id', [new Link('value1'), new Link('value2')]);
+console.log('ID:', link2.id);
+console.log('Values:', link2.values);
+
+// Example 4: Link methods
+const link3 = new Link('source');
+const link4 = new Link('target');
+const combined = link3.combine(link4);
+console.log('Combined:', combined.toString());
+
+// Example 5: FormatOptions
+const formatOptions = new FormatOptions({
+  lessParentheses: true,
+  maxLineLength: 80,
+  indentLongLines: true,
+  maxInlineRefs: 3,
+  groupConsecutive: false,
+  indentString: '  ',
+  preferInline: true,
+});
+
+// Example 6: Formatting with options
+const formattedLink = link2.format(formatOptions);
+console.log('Formatted:', formattedLink);
+
+// Example 7: FormatConfig (alias for FormatOptions)
+const formatConfig = new FormatConfig({
+  lessParentheses: false,
+  maxInlineRefs: 2,
+});
+
+// Example 8: Format multiple links
+const multipleLinks = [
+  new Link('link1', [new Link('a'), new Link('b')]),
+  new Link('link2', [new Link('c'), new Link('d')]),
+];
+
+const formatted = formatLinks(multipleLinks, formatConfig);
+console.log('Formatted links:\n', formatted);
+
+// Example 9: Parser with options
+const customParser = new Parser({
+  maxInputSize: 5 * 1024 * 1024, // 5MB
+  maxDepth: 500,
+});
+
+// Example 10: Complex parsing
+const complexInput = `
+parent
+  child1
+  child2
+    grandchild
+`;
+
+const complexLinks = customParser.parse(complexInput);
+complexLinks.forEach((link) => {
+  console.log(link.format(true));
+});
+
+// Example 11: Link equality
+const linkA = new Link('id', [new Link('value')]);
+const linkB = new Link('id', [new Link('value')]);
+console.log('Equal:', linkA.equals(linkB));
+
+// Example 12: Link simplification
+const complexLink = new Link(null, [new Link('single')]);
+const simplified = complexLink.simplify();
+console.log('Simplified:', simplified.toString());
+
+// Example 13: Working with quoted references
+const quotedLink = new Link('quoted id', [new Link('value with spaces')]);
+console.log('Escaped:', Link.escapeReference('needs:quoting'));

package/index.d.ts

@@ -0,0 +1,312 @@
+/**
+ * TypeScript type definitions for links-notation
+ *
+ * This module provides TypeScript type definitions for the Links Notation parser.
+ * Links Notation is a format for representing relationships between entities.
+ */
+
+/**
+ * Represents a link with an optional identifier and values.
+ *
+ * A Link can represent:
+ * - A simple reference: `new Link('id')`
+ * - A link with values: `new Link('id', [new Link('child1'), new Link('child2')])`
+ * - A link without an id: `new Link(null, [...])`
+ */
+export class Link {
+  /**
+   * Optional identifier for the link
+   */
+  id: string | null;
+
+  /**
+   * Array of child links/values
+   */
+  values: Link[];
+
+  /**
+   * Create a new Link
+   * @param id - Optional identifier for the link
+   * @param values - Optional array of nested links
+   * @throws {TypeError} If values is not an array or null
+   */
+  constructor(id?: string | null, values?: Link[] | null);
+
+  /**
+   * Convert link to string representation
+   * @returns String representation of the link
+   */
+  toString(): string;
+
+  /**
+   * Get formatted string of all values
+   * @returns Space-separated string of values
+   */
+  getValuesString(): string;
+
+  /**
+   * Simplify the link structure by unwrapping single-value containers
+   * @returns Simplified link
+   */
+  simplify(): Link;
+
+  /**
+   * Combine this link with another link
+   * @param other - The link to combine with
+   * @returns Combined link
+   */
+  combine(other: Link): Link;
+
+  /**
+   * Convert to string using either just ID or full format
+   * @returns String representation
+   */
+  toLinkOrIdString(): string;
+
+  /**
+   * Check equality with another Link
+   * @param other - Object to compare with
+   * @returns True if links are equal
+   */
+  equals(other: any): boolean;
+
+  /**
+   * Format the link as a string
+   * @param lessParentheses - If true, omit parentheses where safe; or a FormatOptions/FormatConfig object
+   * @param isCompoundValue - If true, this is a value in a compound link
+   * @returns Formatted string
+   */
+  format(
+    lessParentheses?: boolean | FormatOptions | FormatConfig,
+    isCompoundValue?: boolean
+  ): string;
+
+  /**
+   * Check if a string needs to be wrapped in parentheses
+   * @param str - The string to check
+   * @returns True if parentheses are needed
+   */
+  needsParentheses(str: string): boolean;
+
+  /**
+   * Get string representation of a value
+   * @param value - The value to stringify
+   * @returns String representation
+   */
+  static getValueString(value: Link): string;
+
+  /**
+   * Escape a reference string by adding quotes if necessary
+   * @param reference - The reference to escape
+   * @returns Escaped reference
+   */
+  static escapeReference(reference: string): string;
+}
+
+/**
+ * Parser options for configuring the parser behavior
+ */
+export interface ParserOptions {
+  /**
+   * Maximum input size in bytes (default: 10MB)
+   */
+  maxInputSize?: number;
+
+  /**
+   * Maximum nesting depth (default: 1000)
+   */
+  maxDepth?: number;
+}
+
+/**
+ * Parser for Links Notation format
+ *
+ * The Parser class converts Links Notation strings into Link objects.
+ */
+export class Parser {
+  /**
+   * Maximum input size in bytes
+   */
+  maxInputSize: number;
+
+  /**
+   * Maximum nesting depth
+   */
+  maxDepth: number;
+
+  /**
+   * Create a new Parser instance
+   * @param options - Parser options
+   */
+  constructor(options?: ParserOptions);
+
+  /**
+   * Parse Lino notation text into Link objects
+   * @param input - The Lino notation text to parse
+   * @returns Array of parsed Link objects
+   * @throws {Error} If parsing fails
+   */
+  parse(input: string): Link[];
+}
+
+/**
+ * Options for formatting links
+ */
+export interface FormatOptionsConfig {
+  /**
+   * If true, omit parentheses where safe (default: false)
+   */
+  lessParentheses?: boolean;
+
+  /**
+   * Maximum line length before auto-indenting (default: 80)
+   */
+  maxLineLength?: number;
+
+  /**
+   * If true, indent lines exceeding maxLineLength (default: false)
+   */
+  indentLongLines?: boolean;
+
+  /**
+   * Maximum number of references before auto-indenting (default: null)
+   */
+  maxInlineRefs?: number | null;
+
+  /**
+   * If true, group consecutive links with same ID (default: false)
+   */
+  groupConsecutive?: boolean;
+
+  /**
+   * String to use for indentation (default: "  ")
+   */
+  indentString?: string;
+
+  /**
+   * If true, prefer inline format when under thresholds (default: true)
+   */
+  preferInline?: boolean;
+}
+
+/**
+ * FormatOptions for Lino notation formatting.
+ *
+ * Provides configuration options for controlling how Link objects are formatted.
+ */
+export class FormatOptions {
+  /**
+   * If true, omit parentheses where safe
+   */
+  lessParentheses: boolean;
+
+  /**
+   * Maximum line length before auto-indenting
+   */
+  maxLineLength: number;
+
+  /**
+   * If true, indent lines exceeding maxLineLength
+   */
+  indentLongLines: boolean;
+
+  /**
+   * Maximum number of references before auto-indenting
+   */
+  maxInlineRefs: number | null;
+
+  /**
+   * If true, group consecutive links with same ID
+   */
+  groupConsecutive: boolean;
+
+  /**
+   * String to use for indentation
+   */
+  indentString: string;
+
+  /**
+   * If true, prefer inline format when under thresholds
+   */
+  preferInline: boolean;
+
+  /**
+   * Create a new FormatOptions instance
+   * @param options - Configuration options
+   */
+  constructor(options?: FormatOptionsConfig);
+
+  /**
+   * Check if line should be indented based on length
+   * @param line - The line to check
+   * @returns True if line should be indented based on length threshold
+   */
+  shouldIndentByLength(line: string): boolean;
+
+  /**
+   * Check if link should be indented based on reference count
+   * @param refCount - Number of references in the link
+   * @returns True if link should be indented based on reference count threshold
+   */
+  shouldIndentByRefCount(refCount: number): boolean;
+}
+
+/**
+ * FormatConfig is an alias for FormatOptions to maintain API consistency
+ * with the Python implementation.
+ *
+ * This is an alias for FormatOptions to maintain API consistency across languages.
+ * Python uses 'FormatConfig', so this export provides the same name for JavaScript.
+ */
+export class FormatConfig extends FormatOptions {
+  /**
+   * Create a new FormatConfig instance
+   * @param options - Configuration options
+   */
+  constructor(options?: FormatOptionsConfig);
+}
+
+/**
+ * Container for grouping related links
+ */
+export class LinksGroup {
+  /**
+   * The element associated with this group
+   */
+  element: any;
+
+  /**
+   * Child groups or links
+   */
+  children: (LinksGroup | Link)[];
+
+  /**
+   * Create a new LinksGroup
+   * @param element - The element for this group
+   * @param children - Optional array of child groups or links
+   */
+  constructor(element: any, children?: (LinksGroup | Link)[]);
+
+  /**
+   * Convert the group to a flat list
+   * @returns Flattened list of elements
+   */
+  toList(): any[];
+
+  /**
+   * Convert the group to a string representation
+   * @returns String representation of the group
+   */
+  toString(): string;
+}
+
+/**
+ * Format an array of links as a string
+ * @param links - Array of links to format
+ * @param lessParentheses - If true, omit parentheses where safe; or a FormatOptions/FormatConfig object
+ * @returns Formatted string with each link on a new line
+ */
+export function formatLinks(
+  links: Link[],
+  lessParentheses?: boolean | FormatOptions | FormatConfig
+): string;

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "links-notation",
-  "version": "0.13.0",
+  "version": "0.16.0",
   "description": "Links Notation parser for JavaScript",
   "main": "dist/index.js",
+  "types": "index.d.ts",
   "type": "module",
   "scripts": {
     "build": "bun run build:grammar && bun build src/index.js --outdir=dist --target=node",
@@ -10,7 +11,9 @@
     "test": "bun test",
     "test:watch": "bun test --watch",
     "lint": "eslint src/ tests/",
-    "lint:fix": "eslint src/ tests/ --fix"
+    "lint:fix": "eslint src/ tests/ --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   },
   "keywords": [
     "lino",
@@ -20,10 +23,19 @@
   ],
   "author": "",
   "license": "Unlicense",
-  "devDependencies": {
-    "bun-types": "^1.2.19",
-    "eslint": "^8.56.0",
-    "peggy": "^5.0.6"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/link-foundation/links-notation.git"
+  },
+  "bugs": {
+    "url": "https://github.com/link-foundation/links-notation/issues"
   },
-  "dependencies": {}
+  "homepage": "https://github.com/link-foundation/links-notation#readme",
+  "devDependencies": {
+    "bun-types": "^1.4.0",
+    "eslint": "^10.9.1",
+    "peggy": "^5.1.0",
+    "prettier": "^3.9.6",
+    "typescript": "^7.0.2"
+  }
 }

package/src/Link.js

@@ -82,10 +82,16 @@ export class Link {
    * @returns {string} Escaped reference
    */
   static escapeReference(reference) {
-    if (!reference || reference.trim() === '') {
+    if (reference === null || reference === undefined) {
       return '';
     }
 
+    // The empty reference is written as a bare delimiter pair, so that it reads
+    // back as itself instead of disappearing from the document.
+    if (reference === '') {
+      return '""';
+    }
+
     const hasSingleQuote = reference.includes("'");
     const hasDoubleQuote = reference.includes('"');
 

package/src/Parser.js

@@ -64,7 +64,11 @@ export class Parser {
     if (item.children && item.children.length > 0) {
       // Special case: If this is an ID with empty values but has children,
       // the children should become the values of the link (indented ID syntax)
-      if (item.id && (!item.values || item.values.length === 0)) {
+      if (
+        item.id !== undefined &&
+        item.id !== null &&
+        (!item.values || item.values.length === 0)
+      ) {
         const childValues = item.children.map((child) => {
           // For indented children, extract the actual reference from the child's values
           if (child.values && child.values.length === 1) {
@@ -135,6 +139,30 @@ export class Parser {
     return combined;
   }
 
+  /**
+   * Transform the links of a nested (parenthesised) context into a single Link.
+   * The nested context is parsed with the same rules as the root, so it yields
+   * a list of links; a single link is used as is, several links become the
+   * values of one anonymous link. An already parenthesised single link keeps
+   * its own group so that `((a b))` stays distinct from `(a b)`.
+   * @param {Array} nested - Raw items parsed inside the parentheses
+   * @returns {Link} The link representing the parenthesised group
+   */
+  transformNested(nested) {
+    const nestedLinks = [];
+    for (const item of nested) {
+      if (item !== null && item !== undefined) {
+        this.collectLinks(item, [], nestedLinks);
+      }
+    }
+    const wrapsSingleGroup =
+      nested.length === 1 && nested[0] && nested[0].nested !== undefined;
+    if (nestedLinks.length === 1 && !wrapsSingleGroup) {
+      return nestedLinks[0];
+    }
+    return new Link(null, nestedLinks);
+  }
+
   /**
    * Transform a parsed item into a Link object
    * @param {*} item - The item to transform
@@ -148,6 +176,11 @@ export class Parser {
       return item;
     }
 
+    // Parenthesised group parsed as a nested context
+    if (item.nested !== undefined) {
+      return this.transformNested(item.nested);
+    }
+
     // Handle simple reference objects like {id: 'a'}
     if (item.id !== undefined && !item.values && !item.children) {
       return new Link(item.id);
@@ -156,12 +189,12 @@ export class Parser {
     // For items with values, create a link with those values
     if (item.values && Array.isArray(item.values)) {
       // Create a link with id (if present) and transformed values
-      const link = new Link(item.id || null, []);
+      const link = new Link(item.id ?? null, []);
       link.values = item.values.map((v) => this.transformLink(v));
       return link;
     }
 
     // Default case
-    return new Link(item.id || null, []);
+    return new Link(item.id ?? null, []);
   }
 }