tessl/npm-vue--shared

Internal utility functions shared across Vue.js packages for DOM manipulation, type checking, and general utilities

—

Pending

Overview

Eval results

Files

Display and Formatting

Name: tessl/npm-vue--shared
Author: tessl

Utilities for converting values to display strings, formatting data for user presentation, and generating error-friendly code frames for debugging.

Capabilities

Display String Conversion

Functions for converting any JavaScript value to a user-friendly string representation.

/**
 * Convert any value to a display string for template interpolation
 * Handles refs, objects, arrays, and primitive types intelligently
 * @param val - Value to convert to display string
 * @returns String representation suitable for display
 */
function toDisplayString(val: unknown): string;

Code Frame Generation

Functions for generating formatted code frames that highlight specific regions of source code.

/**
 * Generate a formatted code frame showing source code with line numbers
 * Highlights a specific range and provides context lines around it
 * @param source - Source code string to generate frame from
 * @param start - Start position to highlight (default: 0)
 * @param end - End position to highlight (default: source.length)
 * @returns Formatted code frame with line numbers and highlighting
 */
function generateCodeFrame(
  source: string,
  start?: number,
  end?: number
): string;

Usage Examples:

import { toDisplayString, generateCodeFrame } from "@vue/shared";

// Basic value conversion
console.log(toDisplayString("hello")); // "hello"
console.log(toDisplayString(42)); // "42"
console.log(toDisplayString(true)); // "true"
console.log(toDisplayString(null)); // ""
console.log(toDisplayString(undefined)); // ""

// Array conversion
const arr = [1, 2, { name: "test" }];
console.log(toDisplayString(arr));
// Formatted JSON with proper indentation:
// [
//   1,
//   2,
//   {
//     "name": "test"
//   }
// ]

// Object conversion
const obj = { 
  name: "John", 
  age: 30, 
  active: true,
  toString: () => "Custom toString" // Ignored - uses JSON.stringify
};
console.log(toDisplayString(obj));
// {
//   "name": "John",
//   "age": 30,
//   "active": true
// }

// Special object handling
const specialObj = {
  name: "test",
  toString: Object.prototype.toString // Uses JSON.stringify
};
console.log(toDisplayString(specialObj)); // JSON formatted

const customToString = {
  name: "test",
  toString: () => "Custom representation"
};
console.log(toDisplayString(customToString)); // "Custom representation"

// Map and Set handling
const map = new Map([
  ["key1", "value1"],
  [Symbol("sym"), "symbolValue"],
  [123, "numberKey"]
]);
console.log(toDisplayString(map));
// {
//   "Map(3)": {
//     "key1 =>": "value1",
//     "Symbol(sym) =>": "symbolValue", 
//     "123 =>": "numberKey"
//   }
// }

const set = new Set([1, "hello", Symbol("test")]);
console.log(toDisplayString(set));
// {
//   "Set(3)": [
//     1,
//     "hello",
//     "Symbol(test)"
//   ]
// }

// Symbol handling
const sym = Symbol("description");
console.log(toDisplayString(sym)); // "Symbol(description)"

const anonSym = Symbol();
console.log(toDisplayString(anonSym)); // "Symbol()"

// Code frame generation
const sourceCode = `function hello() {
  const message = "Hello World";
  console.log(message);
  return message;
}`;

// Highlight specific range
const frame = generateCodeFrame(sourceCode, 25, 45);
console.log(frame);
// Output:
// 1  |  function hello() {
// 2  |    const message = "Hello World";
//    |                     ^^^^^^^^^^^^^
// 3  |    console.log(message);
// 4  |    return message;
// 5  |  }

// Highlight entire line
const lineFrame = generateCodeFrame(sourceCode, 20, 50);
console.log(lineFrame);

// Error position highlighting
const errorCode = `const x = 1 +;
const y = 2;`;

const errorFrame = generateCodeFrame(errorCode, 12, 13);
console.log(errorFrame);
// Output:
// 1  |  const x = 1 +;
//    |              ^
// 2  |  const y = 2;

Display String Conversion Rules

toDisplayString follows these conversion rules:

Strings: Return as-is
null/undefined: Return empty string ""
Arrays: Use JSON.stringify with 2-space indentation
Objects:
- If has custom toString (not Object.prototype.toString): Use it
- Otherwise: Use JSON.stringify with 2-space indentation
Maps: Convert to object notation showing entries
Sets: Convert to array notation showing values
Symbols: Show with description Symbol(description)
Refs: Recursively convert the .value property
Other: Use String() conversion

Code Frame Features

Line Numbering: Automatic line number generation with consistent padding Context Lines: Shows 2 lines before and after the highlighted region Range Highlighting: Uses ^ characters to mark the specific range Multi-line Support: Handles ranges spanning multiple lines Edge Cases: Safely handles out-of-bounds positions

Advanced Usage Examples

// Vue ref handling (when available)
import { ref } from 'vue';
const reactiveValue = ref({ count: 5 });
console.log(toDisplayString(reactiveValue)); 
// Shows the value, not the ref wrapper:
// {
//   "count": 5
// }

// Nested ref handling
const nestedRef = ref(ref("nested"));
console.log(toDisplayString(nestedRef)); // "nested"

// Complex nested structures
const complex = {
  users: new Map([
    ["john", { age: 30, roles: new Set(["admin", "user"]) }]
  ]),
  settings: [
    { key: "theme", value: "dark" },
    { key: "lang", value: "en" }
  ]
};

console.log(toDisplayString(complex));
// Properly formatted with Map and Set representations

// Code frame for syntax errors
const syntaxError = `import { computed } from 'vue'

const value = computed(( => {
  return state.count * 2
})`;

const frame = generateCodeFrame(syntaxError, 45, 46);
// Points to the syntax error position

Integration with Vue

These utilities are integral to Vue's template system:

Template Interpolation: toDisplayString formats {{ }} expressions
Error Reporting: generateCodeFrame shows exact error locations in templates
Development Tools: Better debugging experience with formatted output
SSR: Consistent string conversion across server and client rendering