shelving/util/template.d.ts

Toolkit for using data in JavaScript.

import type { ImmutableArray } from "./array.js";
import { type ImmutableDictionary } from "./dictionary.js";
import type { NotString } from "./string.js";
/** Template values in `{ placeholder: value }` format. */
type TemplateValues = ImmutableDictionary<string>;
/** Things that can be converted to the value for a named placeholder. */
type PlaceholderValues = string | ((name: string) => string) | ImmutableArray<string> | TemplateValues;
/**
 * Get list of placeholders named in a template string.
 *
 * @param template The template including template placeholders, e.g. `:name-${country}/{city}`
 * @returns Array of clean string names of found placeholders, e.g. `["name", "country", "city"]`
 */
export declare function getPlaceholders(template: string): readonly string[];
/**
 * Match a template against a target string.
 * - Turn ":year-:month" and "2016-06..." etc into `{ year: "2016"... }`
 *
 * @param templates Either a single template string, or an iterator that returns multiple template template strings.
 * - Template strings can include placeholders (e.g. `:name-${country}/{city}`).
 * @param target The string containing values, e.g. `Dave-UK/Manchester`
 * @return An object containing values, e.g. `{ name: "Dave", country: "UK", city: "Manchester" }`, or undefined if target didn't match the template.
 */
export declare function matchTemplate(template: string, target: string): TemplateValues | undefined;
/**
 * Match multiple templates against a target string and return the first match.
 */
export declare function matchTemplates(templates: Iterable<string> & NotString, target: string): TemplateValues | undefined;
/**
 * Turn ":year-:month" and `{ year: "2016"... }` etc into "2016-06..." etc.
 *
 * @param template The template including template placeholders, e.g. `:name-${country}/{city}`
 * @param values An object containing values, e.g. `{ name: "Dave", country: "UK", city: "Manchester" }` (functions are called, everything else converted to string), or a function or string to use for all placeholders.
 * @return The rendered string, e.g. `Dave-UK/Manchester`
 *
 * @throws {ReferenceError} If a placeholder in the template string is not specified in values.
 */
export declare function renderTemplate(template: string, values: PlaceholderValues): string;
export {};