@xmachines/play-url

The URL layer of the XMachines Play Architecture.

Installation

pnpm add @xmachines/play-url

Peer dependencies. Install them with the package:

pnpm add @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, createPatternCache | 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