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 { AnyCaller } from "./function.js";
import type { NotString } from "./string.js";
/** Dictionary of named template values in `{ myPlaceholder: "value" }` format. */
export type TemplateDictionary = ImmutableDictionary<string>;
/** Callback that returns the right replacement string for a given placeholder. */
export type TemplateCallback = (placeholder: string) => string;
/**
 * Things that can be converted to the value for a named placeholder.
 *
 * `string` — Single string used for every `{placeholder}`
 * `ImmutableArray<string>` — Array of strings (or functions that return strings) used for `*` numbered placeholders e.g. `["John"]`
 * `TemplateValues` — Object containing named strings used for named placeholders, e.g. `{ myPlaceholder: "Ellie" }`
 * `TemplateCallback` — Function that returns the right string for a named `{placeholder}`.v
 */
export type TemplateValues = string | ImmutableArray<string> | TemplateDictionary | TemplateCallback;
/**
 * 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, caller?: AnyCaller): TemplateDictionary | undefined;
/**
 * Match multiple templates against a target string and return the first match.
 */
export declare function matchTemplates(templates: Iterable<string> & NotString, target: string): TemplateDictionary | 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 {RequiredError} If a placeholder in the template string is not specified in values.
 */
export declare function renderTemplate(template: string, values: TemplateValues, caller?: AnyCaller): string;