svelte-guard-history-router

svelte guarded history router

Features

• Named params article/:id
• Guards to act when entering or leaving a route
• Automatic route ranking (more specific routes have higher priority)
• Routes and keys acting as stores
• Nested Routes with relative paths for route composition (Shared Leave Routes)
• Route values
• Object <=> parameter mapping
• Create links from objects
• Standart <a href="/home">Home</a> elements

Shared Leave Routes

<DetailRoute>
    <Route path="/detail/:detail"/>
</DetailRoute>

<Router>
    <Route path="/subjectA">
        <DetailRoute/>
    </Route>
    <Route path="/subjectB">
        <DetailRoute/>
    </Route>
</Router>

usage

<script>
  import { Router, Route, Outlet, redirectGuard } from "svelte-guard-history-router";
  import About from "./About.svelte";
  import Categories from "./Categories.svelte";
  import Category from "./Category.svelte";
  import Articles from "./Articles.svelte";
  import Article from "./Article.svelte";

  import { enshureSession } from "./main.mjs";

  export const enshureSession = redirectGuard("/login", () => !session);
  let session = undefined;
</script>

<Router base="/base">
<nav>
  <!-- catch all but link to '/' -->
  <Route href="/" path="*" component={Home}>Router Example</Route>
  <ul class="left">
    <li>
      <Route path="/about" component={About}>About</Route>
    </li>
    <li>
      <Route path="/article" guards={enshureSession} component={Articles}>
        Articles
        <Route path="/:artice" component={Article}/>
      </Route>
    </li>
    <li>
      <Route path="/category" guards={enshureSession} component={Categories}>
        Categories
        <Route path="/:category" component={Category}/>
      </Route>
    </li>
  </ul>
</nav>
<main>
  <Outlet/>
</main>
</Router>

Sample code

Check out the code in the example folder, or the live example.

To run the sample, clone the repository, install the dependencies, and start:

git clone https://github.com/arlac77/svelte-guard-history-router
cd svelte-guard-history-router
npm install
npm start

then navigate to localhost:5000

run tests

export BROWSER=safari|chrome|...
yarn test
or
npm test

API

Table of Contents

• active
  • Parameters
• Key
  • Properties
• BaseRouter
  • Parameters
  • Properties
  • component
  • value
  • path
  • path
    • Parameters
  • replace
    • Parameters
  • push
    • Parameters
  • finalizePush
    • Parameters
  • continue
    • Parameters
  • abort
    • Parameters
  • subscribe
    • Parameters
  • updateActive
    • Parameters
  • addRoute
    • Parameters
  • routeFor
    • Parameters
  • pathFor
    • Parameters
• BaseTransition
  • searchParams
  • searchParams
    • Parameters
  • nest
    • Parameters
  • continue
  • abort
    • Parameters
• DetailRoute
  • Properties
  • master
  • first
  • last
  • previous
  • next
• Guard
  • enter
    • Parameters
  • leave
    • Parameters
• redirectGuard
  • Parameters
• sequenceGuard
  • Parameters
• parallelGuard
  • Parameters
• MasterRoute
  • Parameters
  • Properties
• nullGuard
• RootRoute
  • hasParams
  • path
  • propertyMapping
  • guard
• SkeletonRoute
  • Parameters
  • Properties
  • enter
    • Parameters
  • leave
    • Parameters
  • isAcceptable
    • Parameters
  • propertiesFor
    • Parameters
  • commonAncestor
    • Parameters
  • valueFor
    • Parameters
  • value
  • propertyMapping
  • objectInstance
• ValueStoreRoute
• Transition
  • Parameters
  • Properties
  • start
  • end
  • redirect
    • Parameters
  • abort
    • Parameters
• findClosestAttribute
  • Parameters
• dispatchNavigationEvent
  • Parameters
• nameValueStore
  • Parameters
  • Properties
• WaitingGuard
  • Parameters

active

• See: {Router.updateActive}

Keeps the node active state in sync.

Parameters

• node Element
• router Router

Key

Keys also act as svelte stores and can be subscribed.

export const article = derived(
[articles, router.keys.article],
([$articles, $id], set) => {
  set($articles.find(a => a.id === $id));
  return () => {};
}
);

Type: Object

Properties

• name string
• value any
• subscriptions Set

BaseRouter

Extends BaseTransition

key subscriptions:

const aKey = router.keys.aKey;
$aKey // fired if value of aKey changes

Parameters

• routes Array<Route> all managed routes
• base string url (optional, default new URL("../",import.meta.url).pathname)

Properties

• linkNodes Set<Node> nodes having their active state updated
• routes Array<Route>
• keys Object collected keys of all routes
• params Object value mapping from keys (from current route)
• route Route current
• nested Transition ongoing nested transition
• base string url

component

Current component. Either from a nested transition or from the current route

Returns SvelteComponent

value

Value if the current route

Returns any

path

Returns string url path with fragment & query

path

Replace current route.

Parameters

• path string

replace

Replace current route without updating the state.

Parameters

• path string

Returns Object former state

push

Leave current route and enter route for given path. The work is done by a Transition.

Parameters

• path string where to go

Returns Transition running transition

finalizePush

Called from a Transition to manifest the new destination. If path is undefined the Transition has been aborderd.

Parameters

• path string

continue

Continue a transition to its original destination. Shortcut for this.transition.continue(). If there is no transition ongoing and a fallbackPath is present, it will be entered. Otherwise does nothing.

Parameters

• fallbackPath string

abort

Abort a transition. Shortcut for this.transition.abort() If there is no transition ongoing and a fallbackPath is present it will be entered. Otherwise does nothing.

Parameters

• fallbackPath string

subscribe

Router subscription. Changes in the current route will trigger a update

Parameters

• subscription Function

updateActive

Update the active state of a node. A node is considered active if it shared the path prefix with the current route.

Parameters

• node Element

addRoute

Add a new Route.

Parameters

• route Route

routeFor

Find Route for a given value.

Parameters

• value any

Returns Route able to support given value

pathFor

Find path for a given value.

Parameters

• value any
• suffix string to be appended

Returns string path + suffix

BaseTransition

searchParams

Deliver url search params form the current location.

Returns URLSearchParams as extracted from the path

searchParams

Replaces the search part of the path with the given searchParams.

Parameters

• searchParams (URLSearchParams | Object)

nest

Add another transition nesting level. Starts a transition from the given factory.

Parameters

• path string
• factory Transition

continue

Continue a nested route to its original destination. Does nothing if the transition has not been nested.

abort

Abort the transition.

Parameters

• error

Returns Promise<boolean> truen in case there was a nesten transition

DetailRoute

Extends ValueStoreRoute

Route to represent a slice of the masters list of values.

Properties

• master Route route holding the master records

master

Route holding the list ov values

Returns Route our master

first

Returns Promise<any> 1st. entry

last

Returns any last entry

previous

Returns any previous value

next

Returns Promise<any> next value

Guard

Enforces conditions of routes Like the presents of values in the context

enter

Called while entering a route (current outlet is not yet set)

Parameters

• transition Transition

leave

Called before leaving a route

Parameters

• transition Transition

redirectGuard

Redirects to a given path if condition is met.

Parameters

• path string
• condition Function redirects when returning true

sequenceGuard

Execute guards in a sequence.

Parameters

• children Iterable<Guard>

parallelGuard

Execute guards in a parallel.

Parameters

• children Iterable<Guard>

MasterRoute

Extends SkeletonRoute

Route holding a ordered collection of values.

Parameters

• path
• options

Properties

• value Array<any>

nullGuard

Default empty guard does nothing.

RootRoute

Route at the root of the tree. This route has no parent. All other routes are below of this one.

hasParams

Are there parameters in the path.

Returns boolean true if route has parameters (:key)

path

Returns string empty as we are the root

propertyMapping

Returns Object empty object

guard

Returns Guard empty guard which does nothing

SkeletonRoute

Extends RootRoute

Route Subscriptions on Routes fire when the route value changes.

Parameters

• path
• options (optional, default {})

Properties

• path string full path of the Route including all parents
• component SvelteComponent target to show
• linkComponent SvelteComponent content for ObjectLink
• propertyMapping Object Map properties to object attributes Keys are the property names and values are the keys in the resulting object.
• priority number
• keys Array<string> as found in the path
• regex RegEx
• value any

enter

Enter the route from a former one. All parent routes up to the common ancestor are entered first.

Parameters

• transition Transition
• untilRoute Route the common ancestor with the former route

leave

Leave the route to a new one. All parent routes up to the common ancestor are left.

Parameters

• transition Transition
• untilRoute Route the common ancestor with the future route

isAcceptable

Check if value and properties are acceptable for the route.

Parameters

• value any to be placed into route
• properties Object as presented in the route

Returns boolean true if value can be accepted

propertiesFor

Extract properties from a value. All property values must be strings.

Parameters

• value any source of the properties

Returns (Object | undefined) properties extracted from given value

commonAncestor

Find common ancestor with an other Route.

Parameters

• other Route

Returns (Route | undefined) common ancestor Route between receiver and other

valueFor

Deliver value for a given set of properties of the transition. Default implemantation asks the parent route.

Parameters

• transition Transition

Returns any for matching properties

value

Deliver route value. Default implemantation asks the parent route.

Returns any

propertyMapping

Deliver property mapping. Default implemantation asks the parent route.

Returns Object for matching properties

objectInstance

Default implemantation asks the parent route.

ValueStoreRoute

Extends SkeletonRoute

Route holding a single value

Transition

Extends BaseTransition

Transition between routes.

Parameters

• router Router
• path string new destination

Properties

• router Router
• path string new destination

start

Start the transition

• leave old route
• find matching target route @see matcher()
• enter new route
• set params
• set current route

end

• See: Router.finalizePush

Cleanup transition. Update Nodes active state

redirect

Halt current transition and go to another route. To proceed with the original route call continue() The original transition will keept in place and can be continued afterwards.

Parameters

• path string new route to enter temporary

abort

Bring back the router into the state before the transition has started. All nested transitions also will be termniated.

Parameters

• e (Exception | undefined)

findClosestAttribute

Walks up the dom tree parents unti a node with a given attribute is found or the root node is reached.

Parameters

• element Element
• attributeName string

Returns (Element | undefined)

dispatchNavigationEvent

Dispatches a NAVIGATION_EVENT with pathname and hash

Parameters

• event Event

nameValueStore

Create a named object which also acts as a store.

Parameters

• name string
• value any initial value

Properties

• value any

Returns Store

WaitingGuard

Extends Guard

Shows a component during transition.

Parameters

• component SvelteComponent to show up during th transition
• rampUpTime number initial delay for the componnt to show up (optional, default 300)

install

With npm do:

npm install svelte-guard-history-router

With yarn do:

yarn add svelte-guard-history-router

SPA integrating with a nginx backend

All unresolvable requests are redirected to /sericeBase/index.html

• /deploymantLocation is the location of the frontend in the servers file system
• /serviceBase is the url path as seen from the browser

location /serviceBase {
  alias /deploymentLocation;
  try_files $uri$args $uri$args/ /serviceBase/index.html;
}

SPA integrating with a netlify

publish a _redirects file into the app root folder

/* /index.html 200

license

BSD-2-Clause