svelte-websocket-store

Svelte store with a websocket backend

import websocketStore from "svelte-websocket-store";

const initialValue = { };
export const myStore = websocketStore("wss://mydomain.com/ws1", initialValue, ['option 1', 'option 2']);


// send JSON to websocket server
$myStore = { content: "to be saved", other_values: "all" };


// receive JSON from server (push)
let response = $myStore;

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
• Entitlement
  • Parameters
• Guard
  • enter
    • Parameters
  • leave
    • Parameters
• redirectGuard
  • Parameters
• sequenceGuard
  • Parameters
• parallelGuard
  • Parameters
• websocketStore
  • Parameters
• login
  • Parameters
• handleFailedResponse
  • 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
• SessionData
  • Properties
• msecsRequiredForRefresh
• supportedTokenTypes
• Session
  • Parameters
  • Properties
  • update
    • Parameters
  • refresh
  • authorizationHeader
  • isValid
  • invalidate
  • hasEntitlement
    • Parameters
  • subscribe
    • Parameters
• decode
  • Parameters
• 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

Entitlement

Parameters

• data (string | Object)

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>

websocketStore

Create a writable store based on a web-socket. Data is transferred as JSON. Keeps socket open (reopens if closed) as long as there are subscriptions.

Parameters

• url string the WebSocket url
• initialValue any store value used before 1st. response from server is present
• socketOptions Array<string> transparently passed to the WebSocket constructor

Returns Store

login

Bring session into the valid state by calling the authorization endpoint and asking for a access_token. Executes a POST on the endpoint url expecting username, and password as json

Parameters

• session Session to be opened
• endpoint string authorization url
• username string id of the user
• password string user credentials
• tokenmap Object token names in response to internal known values (optional, default defaultTokenMap)

Returns Promise<(string | undefined)> error message in case of failure or undefined on success

handleFailedResponse

Extract error description from response.

Parameters

• response Response

Returns Promise<string>

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

SessionData

Data as preserved in the backing store.

Type: Object

Properties

• username string user name (id)
• access_token string JWT token
• refresh_token string JWT token

msecsRequiredForRefresh

Time required to execute a refresh

Type: number

supportedTokenTypes

Session

User session. To create as session backed by browser local storage.

let session = new Session(localStorage);

or by browser session storage

let session = new Session(sessionStorage);

Parameters

• store SessionData (optional, default localStorage)

Properties

• entitlements Set<string>
• subscriptions Set<Object> store subscriptions
• expirationDate Date when the access token expires
• access_token string token itself
• refresh_token string refresh token

update

Consume auth response data and reflect internal state.

Parameters

• data Object

refresh

Refresh with refresh_token.

Returns Promise<boolean> true if refresh was succcessfull false otherwise

authorizationHeader

Http header suitable for fetch.

Returns Object header The http header.

Returns string header.Authorization The Bearer access token.

isValid

As long as the expirationTimer is running we must be valid.

Returns boolean true if session is valid (not expired)

invalidate

Remove all tokens from the session and the backing store.

hasEntitlement

Check presence of an entitlement.

Parameters

• name string of the entitlement

Returns boolean true if the named entitlement is present

subscribe

Fired when the session changes.

Parameters

• subscription Function

decode

Extract and decode the payload.

Parameters

• token string

Returns Object payload object

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-websocket-store

With yarn do:

yarn add svelte-websocket-store

run tests

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

license

BSD-2-Clause