Function: buildPath()

API / @xmachines/play-pattern / buildPath

function buildPath(pattern, params?, options?): PathBuildResult;

Defined in: play-pattern/src/pattern-grammar.ts:713

Builds the path that a pattern describes, with each param filled from params.

This is the OUTBOUND half of the language, and it reads the same parse as the match. The walk drops an optional part that has no value TOGETHER with the / that the part absorbed, which is the prefix rule of the module comment: /settings/:section? builds /settings, and not /settings/.

The function reports a fault through its return value, and it throws never. The reason field names the fault: missing for a param that needs a value and has none, and unresolvable for a param that carries a value no path can hold. A caller raises the error of its own layer — @xmachines/play-xstate raises MissingRouteParamError for the first one and InvalidRouteParamError for the second.

Parameters

Parameter	Type	Description
pattern	string	The route pattern, for example /profile/:userId.
params	PathParams	The value of each param, keyed by the name that the pattern declares.
options?	ParseOptions	-

Returns

PathBuildResult

The path, or the reason that stopped the walk with the param that carries it.

Example

buildPath("/profile/:userId", { userId: "alice" }); // { ok: true, path: "/profile/alice" }
buildPath("/settings/:section?", {}); // { ok: true, path: "/settings" }
buildPath("/tags/c\\+\\+", {}); // { ok: true, path: "/tags/c++" }
buildPath("/profile/:userId", {}); // { ok: false, reason: "missing", missing: "userId" }
buildPath("/files/:name", { name: ".." }); // { ok: false, reason: "unresolvable", … }