svelte-websocket-store

Svelte store with a websocket backend

``js
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

$3

* 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.

$3

* node Element
* router Router

Key

Keys also act as svelte stores and can be subscribed.

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

Type: Object

$3

* name string
* value any
* subscriptions Set

BaseRouter

Extends BaseTransition

key subscriptions:

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

$3

* routes Array\ all managed routes
* base string url (optional, default new URL("../",import.meta.url).pathname)

$3

* linkNodes Set<Node> nodes having their active state updated
* routes Array\
* 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

$3

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

Returns SvelteComponent

$3

Value if the current route

Returns any

$3

Returns string url path with fragment & query

$3

Replace current route.

#### Parameters

* path string

$3

Replace current route without updating the state.

#### Parameters

* path string

Returns Object former state

$3

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

$3

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

#### Parameters

* path string

$3

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

$3

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

$3

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

#### Parameters

* subscription Function

$3

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

$3

Add a new Route.

#### Parameters

* route Route

$3

Find Route for a given value.

#### Parameters

* value any

Returns Route able to support given value

$3

Find path for a given value.

#### Parameters

* value any
* suffix string to be appended

Returns string path + suffix

BaseTransition

$3

Deliver url search params form the current location.

Returns URLSearchParams as extracted from the path

$3

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

#### Parameters

* searchParams (URLSearchParams | Object)

$3

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

#### Parameters

* path string
* factory Transition

$3

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

$3

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.

$3

* master Route route holding the master records

$3

Route holding the list ov values

Returns Route our master

$3

Returns Promise\ 1st. entry

$3

Returns any last entry

$3

Returns any previous value

$3

Returns Promise\ next value

Entitlement

$3

* data (string | Object)

Guard

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

$3

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

#### Parameters

* transition Transition

$3

Called before leaving a route

#### Parameters

* transition Transition

redirectGuard

Redirects to a given path if condition is met.

$3

* path string
* condition Function redirects when returning true

sequenceGuard

Execute guards in a sequence.

$3

* children Iterable<Guard>

parallelGuard

Execute guards in a parallel.

$3

* 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.

$3

* 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

$3

* 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.

$3

* response Response

Returns Promise<string>

MasterRoute

Extends SkeletonRoute

Route holding a ordered collection of values.

$3

* path
* options

$3

* value Array\

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.

$3

Are there parameters in the path.

Returns boolean true if route has parameters (:key)

$3

Returns string empty as we are the root

$3

Returns Object empty object

$3

Returns Guard empty guard which does nothing

SkeletonRoute

Extends RootRoute

Route
Subscriptions on Routes fire when the route value changes.

$3

* path
* options (optional, default {})

$3

* 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

$3

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

$3

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

$3

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

$3

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

$3

Find common ancestor with an other Route.

#### Parameters

* other Route

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

$3

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

$3

Deliver route value.
Default implemantation asks the parent route.

Returns any

$3

Deliver property mapping.
Default implemantation asks the parent route.

Returns Object for matching properties

$3

Default implemantation asks the parent route.

ValueStoreRoute

Extends SkeletonRoute

Route holding a single value

SessionData

Data as preserved in the backing store.

Type: Object

$3

* 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.

`js
let session = new Session(localStorage);
`

or by browser session storage

`js
let session = new Session(sessionStorage);
`

$3

* store SessionData (optional, default localStorage)

$3

* 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

$3

Consume auth response data and reflect internal state.

#### Parameters

* data Object

$3

Refresh with refresh\_token.

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

$3

Http header suitable for fetch.

Returns Object header The http header.

Returns string header.Authorization The Bearer access token.

$3

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

Returns boolean true if session is valid (not expired)

$3

Remove all tokens from the session and the backing store.

$3

Check presence of an entitlement.

#### Parameters

* name string of the entitlement

Returns boolean true if the named entitlement is present

$3

Fired when the session changes.

#### Parameters

* subscription Function

decode

Extract and decode the payload.

$3

* token string

Returns Object payload object

Transition

Extends BaseTransition

Transition between routes.

$3

* router Router
* path string new destination

$3

* router Router
* path string new destination

$3

Start the transition

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

$3

* See: Router.finalizePush

Cleanup transition.
Update Nodes active state

$3

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

$3

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.

$3

* element Element
* attributeName string

Returns (Element | undefined)

dispatchNavigationEvent

Dispatches a NAVIGATION\_EVENT with pathname and hash

$3

* event Event

nameValueStore

Create a named object which also acts as a store.

$3

* name string
* value any initial value

$3

* value any

Returns Store

WaitingGuard

Extends Guard

Shows a component during transition.

$3

* 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:

`shell
npm install svelte-websocket-store
`

With yarn do:

`shell
yarn add svelte-websocket-store
`

run tests

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

license

BSD-2-Clause