links-notation 0.23.0 → 0.24.0

package/index.d.ts

@@ -561,3 +561,8 @@ export class BinaryLinoCodec {
 }
 export function formatBinaryDocument(document: Link[]): string;
 export function formatBinaryReference(reference: string): string;
+
+/** Encode exact Unicode as a version 1 UTF-8 hex literal (~1{...}). Throws on unpaired surrogates. */
+export function encodeReferenceLiteral(text: string): string;
+/** Decode a complete literal. Throws on malformed hex, UTF-8, or unsupported versions. */
+export function decodeReferenceLiteral(literal: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "links-notation",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Links Notation parser for JavaScript",
   "main": "dist/index.js",
   "types": "index.d.ts",

package/src/Binary.js

@@ -1,5 +1,6 @@
 /** Binary links notation v1. Packet and document layers share no transport. */
 import { Link } from './Link.js';
+import { formatReference } from './ReferenceLiteral.js';
 import { Parser } from './Parser.js';
 
 const U64 = (1n << 64n) - 1n;
@@ -695,26 +696,7 @@ function canonical(node) {
   return new Link(node.id, node.values.map(canonical));
 }
 export function formatBinaryReference(text) {
-  if (
-    text &&
-    !text.startsWith('#') &&
-    !/[\p{White_Space}\u001c-\u001f\ufeff():"'`]/u.test(text)
-  )
-    return text;
-  let choice = null;
-  for (const quote of ["'", '"', '`'])
-    if (!text.startsWith(quote)) {
-      let longest = 0,
-        run = 0;
-      for (const c of text) {
-        run = c === quote ? run + 1 : 0;
-        longest = Math.max(longest, run);
-      }
-      const count = (longest + 1) | 1;
-      if (choice === null || count < choice.count) choice = { quote, count };
-    }
-  const delimiter = choice.quote.repeat(choice.count);
-  return delimiter + text + delimiter;
+  return formatReference(text);
 }
 export function formatBinaryDocument(document) {
   function nested(node, top = false) {

package/src/Link.js

@@ -1,3 +1,5 @@
+import { formatReference } from './ReferenceLiteral.js';
+
 export class Link {
   /**
    * Create a new Link
@@ -86,53 +88,7 @@ export class Link {
       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('"');
-
-    // A reference that begins with a `#` has to be quoted, or it would read
-    // back as a comment. A `#` anywhere else in a reference is content
-    // (`issue#1047`), so only the first character matters.
-    const needsQuoting =
-      reference.startsWith('#') ||
-      reference.includes(':') ||
-      reference.includes('(') ||
-      reference.includes(')') ||
-      reference.includes(' ') ||
-      reference.includes('\t') ||
-      reference.includes('\n') ||
-      reference.includes('\r') ||
-      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}'`;
-    }
-
-    // Use double quotes if single quotes are present
-    if (hasSingleQuote) {
-      return `"${reference}"`;
-    }
-
-    // Use single quotes for special characters
-    if (needsQuoting) {
-      return `'${reference}'`;
-    }
-
-    // No quoting needed
-    return reference;
+    return formatReference(reference);
   }
 
   /**

package/src/ReferenceLiteral.js

@@ -0,0 +1,66 @@
+/* global TextEncoder, TextDecoder */
+
+/** Detect the reserved versioned-literal prefix at a reference boundary. */
+export function hasReferenceLiteralPrefix(text, start = 0) {
+  return /^~[0-9]+\{/.test(text.slice(start));
+}
+
+/** Encode exact Unicode text as a version 1 UTF-8 hexadecimal reference. */
+export function encodeReferenceLiteral(text) {
+  if (typeof text !== 'string' || !text.isWellFormed()) {
+    throw new TypeError('Reference must be well-formed Unicode text');
+  }
+  const hex = Array.from(new TextEncoder().encode(text), (byte) =>
+    byte.toString(16).padStart(2, '0')
+  ).join('');
+  return `~1{${hex}}`;
+}
+
+/** Decode a complete versioned literal, rejecting malformed bytes and versions. */
+export function decodeReferenceLiteral(literal) {
+  const match = /^~([0-9]+)\{([0-9a-fA-F]*)\}$/.exec(literal);
+  if (
+    !match ||
+    match[0] !== literal ||
+    match[1] !== '1' ||
+    match[2].length % 2 !== 0
+  ) {
+    throw new TypeError(
+      'Invalid or unsupported reference literal (expected ~1{UTF-8 hex})'
+    );
+  }
+  return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(
+    Uint8Array.from(match[2].match(/../g) ?? [], (hex) => parseInt(hex, 16))
+  );
+}
+
+/** Use readable legacy quoting where possible and a literal for empty/control text. */
+export function formatReference(text) {
+  if (typeof text !== 'string' || !text.isWellFormed()) {
+    throw new TypeError('Reference must be well-formed Unicode text');
+  }
+  if (!text || /[\u0000-\u001f\u007f]/u.test(text)) {
+    return encodeReferenceLiteral(text);
+  }
+  if (
+    !text.startsWith('#') &&
+    !/^~[0-9]+\{/.test(text) &&
+    !/[\p{White_Space}\ufeff():"'`]/u.test(text)
+  ) {
+    return text;
+  }
+  let choice = null;
+  for (const quote of ["'", '"', '`']) {
+    if (text.startsWith(quote)) continue;
+    let longest = 0;
+    let run = 0;
+    for (const character of text) {
+      run = character === quote ? run + 1 : 0;
+      longest = Math.max(longest, run);
+    }
+    const count = (longest + 1) | 1;
+    if (choice === null || count < choice.count) choice = { quote, count };
+  }
+  const delimiter = choice.quote.repeat(choice.count);
+  return delimiter + text + delimiter;
+}

package/src/grammar.pegjs

@@ -1,5 +1,6 @@
 {{
   import { DelimitedReferences } from './quotes.js';
+  import { decodeReferenceLiteral, hasReferenceLiteralPrefix } from './ReferenceLiteral.js';
 }}
 
 {
@@ -217,9 +218,18 @@ indentedIdLink = id:reference __ ":" eol { return { id: id, values: [] }; }
 
 // Reference can be quoted (with any number of quotes N >= 1) or simple unquoted
 // Universal approach: use procedural parsing for all quote types and counts
-reference = quotedReference / simpleReference
+reference = referenceLiteral / quotedReference / simpleReference
+
+// Versioned literals reserve ~<version>{<UTF-8 hex>} at a reference boundary.
+// A malformed reserved token must fail rather than fall back to a bare name.
+referenceLiteral = &'~' &{
+  return hasReferenceLiteralPrefix(input, offset());
+} literal:$('~' [0-9]+ '{' [^} \t\r\n()]* '}') {
+  return decodeReferenceLiteral(literal);
+}
 
-simpleReference = chars:referenceSymbol+ { return chars.join(''); }
+simpleReference = &{ return !hasReferenceLiteralPrefix(input, offset()); }
+ chars:referenceSymbol+ { return chars.join(''); }
 
 // Universal quoted reference - handles any N quotes for all quote types
 // Uses procedural parsing with input/offset() for clean, simple logic

package/src/index.js

@@ -1,4 +1,8 @@
 export { Link, formatLinks } from './Link.js';
+export {
+  encodeReferenceLiteral,
+  decodeReferenceLiteral,
+} from './ReferenceLiteral.js';
 export { LinksGroup } from './LinksGroup.js';
 export { Parser, DEFAULT_MAX_DEPTH } from './Parser.js';
 export { StreamParseError, StreamParser } from './StreamParser.js';