links-notation 0.12.0 → 0.15.0

package/eslint.config.js

@@ -0,0 +1,34 @@
+export default [
+  {
+    ignores: ['dist/', 'node_modules/', 'src/parser-generated.js'],
+  },
+  {
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: {
+        // Node.js globals
+        process: 'readonly',
+        Buffer: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        global: 'readonly',
+        // Test framework globals
+        describe: 'readonly',
+        test: 'readonly',
+        it: 'readonly',
+        expect: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        beforeAll: 'readonly',
+        afterAll: 'readonly',
+      },
+    },
+    rules: {
+      'no-unused-vars': 'warn',
+      'no-undef': 'error',
+      semi: ['error', 'always'],
+      quotes: ['warn', 'single', { avoidEscape: true }],
+    },
+  },
+];

package/examples/empty_reference.js

@@ -0,0 +1,43 @@
+// A document written for an object with empty keys, the case that motivated
+// https://github.com/link-foundation/links-notation/issues/288
+//
+// `{"": {"": 1}}` is written as `(o: ("" (o: ("" 1))))`. Every reference in it
+// reads back as itself, so encoders that produce empty keys round trip.
+//
+// Usage: node js/examples/empty_reference.js
+
+import { Parser, formatLinks } from '../src/index.js';
+
+const parser = new Parser();
+
+const source = '(o: ("" (o: ("" 1))))';
+
+console.log('Source:      ', source);
+
+const links = parser.parse(source);
+
+// Show every reference between angle brackets, so an empty one stays visible.
+function render(node) {
+  if (!node.values || node.values.length === 0) {
+    return `<${node.id ?? ''}>`;
+  }
+  const head =
+    node.id === null || node.id === undefined ? '' : `<${node.id}>: `;
+  return `(${head}${node.values.map(render).join(' ')})`;
+}
+
+console.log('Parsed as:   ', links.map(render).join('\n'));
+
+const formatted = formatLinks(links);
+console.log('Formatted:   ', formatted);
+console.log(
+  'Round trips: ',
+  formatLinks(parser.parse(formatted)) === formatted
+);
+
+// A bare delimiter pair is one empty reference, and two in a row stay separate.
+for (const example of ['(a "" b)', '(a "" "" b)', '(a " " b)', '(a ""x"" b)']) {
+  console.log(
+    `${example.padEnd(14)} => ${parser.parse(example).map(render).join(' ')}`
+  );
+}

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,14 +1,19 @@
 {
   "name": "links-notation",
-  "version": "0.12.0",
+  "version": "0.15.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",
     "build:grammar": "peggy --format es -o src/parser-generated.js src/grammar.pegjs",
     "test": "bun test",
-    "test:watch": "bun test --watch"
+    "test:watch": "bun test --watch",
+    "lint": "eslint src/ tests/",
+    "lint:fix": "eslint src/ tests/ --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   },
   "keywords": [
     "lino",
@@ -18,9 +23,19 @@
   ],
   "author": "",
   "license": "Unlicense",
-  "devDependencies": {
-    "bun-types": "^1.2.19",
-    "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.3.14",
+    "eslint": "^10.8.1",
+    "peggy": "^5.1.0",
+    "prettier": "^3.9.6",
+    "typescript": "^7.0.2"
+  }
+}

package/src/FormatOptions.js

@@ -21,7 +21,7 @@ export class FormatOptions {
     this.indentLongLines = options.indentLongLines ?? false;
     this.maxInlineRefs = options.maxInlineRefs ?? null;
     this.groupConsecutive = options.groupConsecutive ?? false;
-    this.indentString = options.indentString ?? "  ";
+    this.indentString = options.indentString ?? '  ';
     this.preferInline = options.preferInline ?? true;
   }