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 { AbsolutePath } from "./path.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 with no separator semantics.
 * - Turn `:year-:month` and `2016-06`... etc into `{ year: "2016"... }`.
 * - Non-catchall placeholders match non-empty values; catchall placeholders (`**`, `:name*`, `{...name}`, etc.) allow empty values.
 *
 * @param template The template string, 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 no match.
 */
export declare function matchTemplate(template: string, target: string, caller?: AnyCaller): TemplateMatches | undefined;
/**
 * Match a path-shaped template against a target path.
 * - Like `matchTemplate`, but with `/` segment semantics: non-catchall placeholders cannot span path segments; catchall placeholders can.
 * - A trailing catchall (e.g. `/files/{...path}`) also matches when the trailing separator is absent (e.g. `/files`), with the catchall value as `""`.
 */
export declare function matchPathTemplate(template: AbsolutePath, target: AbsolutePath, caller?: AnyCaller): TemplateMatches | undefined;
/** Match multiple templates against a target string and return the first match (no separator semantics). */
export declare function matchTemplates(templates: Iterable<string> & NotString, target: string): TemplateMatches | undefined;
/** Match multiple path-shaped templates against a target path and return the first match. */
export declare function matchPathTemplates(templates: Iterable<AbsolutePath> & NotString, target: AbsolutePath): 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;
/**
 * Render a path-shaped template. Behaviourally identical to `renderTemplate` — substitution doesn't need separator awareness — but provided as a sibling to `matchPathTemplate` so callers can pair them.
 */
export declare function renderPathTemplate(template: AbsolutePath, values: TemplateValues, caller?: AnyCaller): AbsolutePath;