@xmachines/play-pattern

API / @xmachines/play-pattern

The route pattern language of the XMachines Play Architecture.

One parse of the URLPattern pathname grammar, and the path that it builds back.

What this package is

URLPattern is the pattern language of XMachines. This package reads a route pattern ONE time and answers every question that a router asks about it, and it writes a path back from the same parse.

parsePattern(pattern) — the parts, the params, which of them a path must fill, whether the pattern needs a match, the bucket key, the bare form, and the literal path.
buildPath(pattern, params) — the path that the pattern describes, with each param filled. It reports a fault through its return value, and it throws never: reason: "missing" for a param that needs a value and has none, and reason: "unresolvable" for a param that carries a value no path can hold, such as a dot segment.
getIndexKey(path) — the bucket key of a concrete path.
isDotSegment(segment) — whether a URL resolves the segment away. buildPath reads it, and @xmachines/play-url reads it for a base path, so ONE definition answers for both.

Both directions read the same parts, so a route that the match reads derives a URL that the match reads back.

What this package is NOT

It holds no URLPattern API. A parse is string work and it needs no constructor, so this package carries no polyfill. @xmachines/play-url holds the API, the base path and the params of a framework router, and it reads this package for the language.

That line is why the package exists. @xmachines/play-xstate BUILDS a URL and matches none, so it reads the grammar and installs no matching machinery for it.

Installation

pnpm add @xmachines/play-pattern @xmachines/core

Peer dependencies. Install them with the package:

@xmachines/core — the base package. This package reads the cache of its cache subpath.

Most applications install it through @xmachines/play-url, which re-exports the language whole. @xmachines/play-router re-exports the part that a router needs: parsePattern, and the cache contract KeyValueCache with its default createLruCache. The cache belongs to @xmachines/core on its cache subpath, and this package re-exports it.

Usage

import { buildPath, parsePattern } from "@xmachines/play-pattern";

parsePattern("/settings/:section?").requiredNames; // []
parsePattern("/docs/:cat-id").names; // ["cat-id"]

buildPath("/profile/:userId", { userId: "alice" }); // { ok: true, path: "/profile/alice" }
buildPath("/settings/:section?", {}); // { ok: true, path: "/settings" }
buildPath("/profile/:userId", {}); // { ok: false, reason: "missing", missing: "userId" }
buildPath("/files/:name", { name: ".." }); // { ok: false, reason: "unresolvable", param: "name", value: ".." }
buildPath("/files/v:version", { version: ".." }); // { ok: true, path: "/files/v.." } — the value shares the segment

The grammar

form	meaning
`/users`	a literal
`:name`	a named param, one path segment
`:name(\d+)`	a named param with a regular expression constraint
`(\d+)`	an anonymous param, numbered from `0`
`*`	an anonymous param that matches every remaining character
`{…}`	a group, which carries its own literals and params
`?` `+` `*`	the modifier of the part before it
`\:`	an escape, which makes the next character a literal

A param name of this library holds a hyphen, which URLPattern does not: /docs/:cat-id is ONE param named cat-id, and ParsedPattern.normalized carries the form that URLPattern compiles. The routing guide states the divergence and which forms each direction reads.

License

MIT

The route pattern language of XMachines.

URLPattern is that language, and this package reads it ONE time for each pattern. parsePattern answers every question that a router asks about a route — which params the pattern declares, which of them a path must fill, whether the pattern needs a match at all, which bucket it belongs to, and which path it matches when every optional part is absent. buildPath walks the SAME parts back into a path, so a route that the match reads derives a URL that the match reads back.

What this package does NOT hold

The URLPattern API. A parse is string work, and it needs no constructor: this package therefore carries no polyfill. @xmachines/play-url holds the API, the base path and the params of a framework router, and it reads this package for the language.

That line is the reason the package exists. @xmachines/play-xstate BUILDS a URL and it matches none, so it reads the grammar and it installs no matching machinery for it.