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, type PossibleString } from "./string.js";
/**
 * Things that can be converted to the value for a named placeholder.
 *
 * `PossibleString` — Single string used for every `{placeholder}`
 * `ImmutableArray<string>` — Array of strings (or functions that return strings) used for `*` numbered placeholders e.g. `["John"]`
 * `ImmutableDictionary<PossibleString>` — Object containing named strings used for named placeholders, e.g. `{ val1: "Ellie", val2: 123 }`
 * `(placeholder: string) => string` — Function that returns the right string for a named `{placeholder}`.v
 */
export type TemplateValues = PossibleString | ImmutableArray<unknown> | ImmutableDictionary<unknown> | ((placeholder: string) => string);
/** The output of matching a template is a dictionary in `{ myPlaceholder: "value" }` format. */
export type TemplateMatches = ImmutableDictionary<string>;
/** List of `{placeholders}` found in a template string. */
export type TemplatePlaceholders = ImmutableArray<string>;
/**
 * 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): TemplatePlaceholders;
/**
 * 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}`).
 * - Template strings do not match the `/` character.
 * - The `**` double splat placeholder _can_ match multiple path segments (e.g. `a/b/c`).
 *
 * @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): TemplateMatches | undefined;
/**
 * Match multiple templates against a target string and return the first match.
 */
export declare function matchTemplates(templates: Iterable<string> & NotString, target: string): TemplateMatches | 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;