Pupa

Pupa is a simple micro templating library for JavaScript that enables string interpolation with placeholder substitution. It supports both object property access and array indexing through a clean brace syntax, includes automatic HTML entity encoding for security, and handles nested object property access through dot notation.

Package Information

• Package Name: pupa
• Package Type: npm
• Language: JavaScript
• Node.js Requirements: >=8
• Installation: npm install pupa

Core Imports

const pupa = require('pupa');

For TypeScript:

import pupa = require('pupa');

Basic Usage

const pupa = require('pupa');

// Object property interpolation
pupa('The mobile number of {name} is {phone.mobile}', {
  name: 'Sindre',
  phone: {
    mobile: '609 24 363'
  }
});
//=> 'The mobile number of Sindre is 609 24 363'

// Array index interpolation
pupa('I like {0} and {1}', ['🦄', '🐮']);
//=> 'I like 🦄 and 🐮'

// HTML-safe interpolation (prevents XSS)
pupa('I like {{0}} and {{1}}', ['<br>🦄</br>', '<i>🐮</i>']);
//=> 'I like &lt;br&gt;🦄&lt;/br&gt; and &lt;i&gt;🐮&lt;/i&gt;'

Capabilities

Template Interpolation

Main templating function that interpolates placeholders in templates with data values. Supports two interpolation modes: plain text replacement and HTML-escaped replacement for security.

/**
 * Simple micro templating function for string interpolation
 * @param {string} template - Text with placeholders for data properties
 * @param {object|unknown[]} data - Data to interpolate into template
 * @returns {string} The template with placeholders replaced by corresponding data values
 * @throws {TypeError} If template is not a string
 * @throws {TypeError} If data is not an object or array
 */
function pupa(template, data);

Template Syntax:

• {key} - Plain interpolation: replaces with string representation of value
• {{key}} - HTML-escaped interpolation: replaces with HTML entity-encoded value to prevent XSS
• {object.property} - Nested object property access using dot notation
• {0}, {1} - Array index access using numeric keys

Parameter Details:

• template (string): Text containing placeholders in {key} or {{key}} format

  • Supports nested property access: {user.profile.name}
  • Supports array indexing: {0}, {1}, etc.
  • Case-sensitive property matching
  • Invalid placeholders are left unchanged in output

• data (object | unknown[]): Data source for placeholder replacement

  • Objects: Properties accessed by key name or dot notation path
  • Arrays: Elements accessed by numeric index
  • Missing properties/indices resolve to empty string
  • All values converted to string representation

Return Value:

• Returns processed template string with placeholders replaced
• HTML entities encoded in double-brace placeholders ({{key}})
• Plain string values in single-brace placeholders ({key})

Error Handling:

• Throws TypeError if template parameter is not a string
• Throws TypeError if data parameter is not an object or array
• Gracefully handles missing properties by substituting empty string
• Invalid placeholder formats are left unchanged in output

Usage Examples:

const pupa = require('pupa');

// Nested object properties
pupa('User {user.name} has email {user.contact.email}', {
  user: {
    name: 'Alice',
    contact: {
      email: 'alice@example.com'
    }
  }
});
//=> 'User Alice has email alice@example.com'

// Array access by index
pupa('Items: {0} and {1}', ['Widget', 'Gadget']);
//=> 'Items: Widget and Gadget'

// Object property access
pupa('Item: {name} costs ${price}', { name: 'Widget', price: 29.99 });
//=> 'Item: Widget costs $29.99'

// HTML escaping for security
pupa('Message: {{userInput}}', { 
  userInput: '<script>alert("xss")</script>' 
});
//=> 'Message: &lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'

// Missing properties become empty strings
pupa('Hello {name}, your score is {score}', { name: 'Bob' });
//=> 'Hello Bob, your score is '

// Type coercion examples
pupa('Count: {count}, Active: {active}', { 
  count: 42, 
  active: true 
});
//=> 'Count: 42, Active: true'

Key Features:

• Lazy evaluation: Templates expand at execution time, not creation time
• Security: Double-brace syntax automatically escapes HTML entities to prevent XSS attacks
• Flexibility: Supports both object property and array index access
• Error resilience: Gracefully handles missing data with empty string substitution
• Nested access: Dot notation for deep object property traversal
• User-supplied templates: Safe for dynamic template strings from external sources
• Performance: Efficient regex-based parsing suitable for high-frequency template rendering