@xmachines/play-url
API / @xmachines/play-url
The URL layer of the XMachines Play Architecture.
Installation
pnpm add @xmachines/play-urlPeer dependencies. Install them with the package:
pnpm add @xmachines/core @xmachines/play@xmachines/play-router depends on this package already. Install it directly when you compile a pattern, join a base path, split a location, or read the params of a framework router yourself. For the pattern grammar alone, install @xmachines/play-pattern.
Overview
URLPattern is the pattern language of XMachines. This package holds the URL layer of it: the compilation of a pattern against the native API or the polyfill, a base path with its :param substitution, the split of a location, 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 pattern LANGUAGE lives in @xmachines/play-pattern. That package carries no URLPattern API and no polyfill, because a parse is string work. This package reads it and re-exports it whole, so @xmachines/play-router needs one manifest entry and one import point for the match.
BOTH directions read that one parse. A URL becomes a state through the match of @xmachines/play-router, and a state becomes a URL through buildPath, which the routing capability of @xmachines/play-xstate calls. That package reads @xmachines/play-pattern directly, so it installs no polyfill. Reach for @xmachines/play-pattern when you need the grammar alone, and for this package when you need the match, a base path, or the params of a framework router.
| Export | Description |
|---|---|
parsePattern, buildPath | The whole pathname grammar of URLPattern, and the path it writes back |
getIndexKey, createLruCache, KeyValueCache | The bucket key of a concrete path, and a cache that a caller owns |
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 |
splitLocation, sanitizePathname | The pathname, the query and the fragment of one location |
resolveFrameworkParams, cleanFrameworkParams, pickOwnParams | The params of a framework router, reconciled with the pattern |
The first two rows come from @xmachines/play-pattern, which this package re-exports whole.
A consumer of this package therefore needs one import point, and one manifest entry.
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