@xmachines/play-url
API / @xmachines/play-url
The URL language of the XMachines Play Architecture.
Installation
pnpm add @xmachines/play-urlPeer dependencies. Install them with the package:
pnpm add @xmachines/play@xmachines/play-router depends on this package already. Install it directly when you read the grammar yourself.
Overview
URLPattern is the pattern language of XMachines, and this package reads it in ONE place: the parser, the compilation of a pattern against the native API or the polyfill, a base path with its :param substitution, and the normalization of the params that a framework router reports.
It knows nothing of a state machine, of a route tree, or of a router bridge. Those live in @xmachines/play-router, which reads this package.
The package exists because BOTH directions need the grammar. A URL becomes a state through the match of @xmachines/play-router, and a state becomes a URL through the substitution of the routing capability of @xmachines/play-xstate. One parser answers both, and neither of those packages depends on the other.
| Export | Description |
|---|---|
parsePattern | The whole pathname grammar of URLPattern, read one time and cached |
getIndexKey | The bucket key of a concrete path |
URLPattern, getCompiledPattern | The native API where a runtime carries it, and the polyfill where it does not |
normalizeBasePath, joinBasePath, stripBasePath | A URL prefix that a host owns, with its :param substitution |
resolveFrameworkParams | The params of a framework router, reconciled with the pattern |
The error classes carry a subpath of their own
@xmachines/play-url/errors exports the three error classes, and the root barrel
exports none of them. Every package of this workspace that raises an error publishes
it the same way: @xmachines/play/errors, @xmachines/play-router/errors,
@xmachines/play-view/errors, @xmachines/play-vue-router/errors and
@xmachines/play-xstate/errors. A module
that needs a catch to name a fault therefore loads the classes alone, with no
pattern parser and no base path:
import { InvalidBasePathError } from "@xmachines/play-url/errors";The API is always present
This package carries urlpattern-polyfill as an ordinary dependency. It uses the native URLPattern when the runtime has one, and the polyfill when it does not. Install nothing, and load nothing.
Documentation
- Routing guide — the pattern grammar, one time, for every adapter
- Architecture
License
MIT