URI Templates (RFC 6570)

/**
 * Create URI template instance for expansion
 * @param expression - URI template expression string
 * @returns URITemplate instance
 */
function URITemplate(expression: string): URITemplate;

/**
 * Expand template with data variables
 * @param data - Object containing template variables
 * @param opts - Expansion options
 * @returns Expanded URI string
 */
URITemplate.prototype.expand(data: object, opts?: object): string;

/**
 * Parse template into component parts
 * @returns Parsed template structure
 */
URITemplate.prototype.parse(): object;

/**
 * Expand parsed template expression
 * @param expression - Parsed template expression
 * @param data - Variable data object
 * @param opts - Expansion options
 * @returns Expanded string
 */
URITemplate.expand(expression: object, data: object, opts?: object): string;

/**
 * Expand named variables
 * @param d - Variable data
 * @param options - Variable options
 * @param explode - Whether to explode arrays/objects
 * @param separator - Separator character
 * @param length - Length limit
 * @param name - Variable name
 * @returns Expanded string
 */
URITemplate.expandNamed(d: any, options: object, explode: boolean, separator: string, length: number, name: string): string;

/**
 * Expand unnamed variables
 * @param d - Variable data
 * @param options - Variable options
 * @param explode - Whether to explode arrays/objects
 * @param separator - Separator character
 * @param length - Length limit
 * @returns Expanded string
 */
URITemplate.expandUnnamed(d: any, options: object, explode: boolean, separator: string, length: number): string;

/**
 * Restore previous URITemplate variable
 * @returns Previous URITemplate variable value
 */
URITemplate.noConflict(): any;

/**
 * Expand URI template and return URI instance
 * @param expression - URI template expression
 * @param data - Template variables
 * @returns URI instance with expanded template
 */
URI.expand(expression: string, data: object): URI;

// Import URITemplate
import URITemplate from 'urijs/src/URITemplate';

// Basic template expansion
const template = new URITemplate('/users/{id}');
const expanded = template.expand({ id: '123' });
console.log(expanded); // '/users/123'

// Multiple variables
const apiTemplate = new URITemplate('/api/{version}/users/{id}{?fields*}');
const apiExpanded = apiTemplate.expand({
  version: 'v1',
  id: '456',
  fields: ['name', 'email', 'created']
});
console.log(apiExpanded); // '/api/v1/users/456?fields=name,email,created'

// Query parameter expansion
const queryTemplate = new URITemplate('/search{?q,limit,offset}');
const queryExpanded = queryTemplate.expand({
  q: 'javascript',
  limit: 10,
  offset: 20
});
console.log(queryExpanded); // '/search?q=javascript&limit=10&offset=20'

// Path segment explosion
const pathTemplate = new URITemplate('/files{/path*}');
const pathExpanded = pathTemplate.expand({
  path: ['docs', 'api', 'reference.html']
});
console.log(pathExpanded); // '/files/docs/api/reference.html'

// Fragment expansion
const fragmentTemplate = new URITemplate('/page{#section}');
const fragmentExpanded = fragmentTemplate.expand({
  section: 'introduction'
});
console.log(fragmentExpanded); // '/page#introduction'

// Complex object expansion
const complexTemplate = new URITemplate('/api{/segments*}{?params*}');
const complexExpanded = complexTemplate.expand({
  segments: ['v2', 'users', '789'],
  params: {
    include: 'profile',
    format: 'json'
  }
});
console.log(complexExpanded); // '/api/v2/users/789?include=profile&format=json'

// Use with URI.js integration
const uriFromTemplate = URI.expand('/api/{version}/users/{id}', {
  version: 'v1',
  id: '123'
});
console.log(uriFromTemplate.toString()); // '/api/v1/users/123'
uriFromTemplate.addQuery('expand', 'profile');
console.log(uriFromTemplate.toString()); // '/api/v1/users/123?expand=profile'

// Reserved character expansion
const reservedTemplate = new URITemplate('/search{/term}{?q}');
const reservedExpanded = reservedTemplate.expand({
  term: 'hello world',
  q: 'special&chars'
});
console.log(reservedExpanded); // '/search/hello%20world?q=special%26chars'

// Length-limited expansion
const limitTemplate = new URITemplate('/short{/name:3}');
const limitExpanded = limitTemplate.expand({
  name: 'verylongname'
});
console.log(limitExpanded); // '/short/ver'

// Form-style query expansion
const formTemplate = new URITemplate('/form{?data*}');
const formExpanded = formTemplate.expand({
  data: {
    firstName: 'John',
    lastName: 'Doe',
    age: 30
  }
});
console.log(formExpanded); // '/form?firstName=John&lastName=Doe&age=30'

// Template cache for performance
URITemplate._cache: object;

// Regular expressions for parsing
URITemplate.EXPRESSION_PATTERN: RegExp;
URITemplate.VARIABLE_PATTERN: RegExp;
URITemplate.VARIABLE_NAME_PATTERN: RegExp;
URITemplate.LITERAL_PATTERN: RegExp;

// Access template cache
console.log(URITemplate._cache); // Object with cached templates

// Parse template manually
const template = new URITemplate('/api/{version}/users{?limit,offset}');
const parsed = template.parse();
console.log(parsed); // Parsed template structure

// Custom template parsing
const customExpression = '{+path}/file{.ext}';
const customTemplate = new URITemplate(customExpression);
const customResult = customTemplate.expand({
  path: 'docs/api',
  ext: 'json'
});
console.log(customResult); // 'docs/api/file.json'

// Handle undefined variables
const undefinedTemplate = new URITemplate('/api/{version}/users/{id?}');
const undefinedResult = undefinedTemplate.expand({
  version: 'v1'
  // id is undefined
});
console.log(undefinedResult); // '/api/v1/users/'

// Use with different variable prefixes
const prefixTemplate = new URITemplate('/api{/segments*}{?query*}{#fragment}');
const prefixResult = prefixTemplate.expand({
  segments: ['v1', 'users'],
  query: { limit: 10 },
  fragment: 'results'
});
console.log(prefixResult); // '/api/v1/users?limit=10#results'