npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@rheactorjs/server

v3.0.1

Published

Core server components for RHeactorJS applications

Downloads

6

Readme

server

npm version Build Status Greenkeeper badge js-standard-style semantic-releaseTest Coverage Code Climate

Core server components for RHeactorJS applications.

The server provides typical business capabilities of a web application:

  • User registration flow
  • Login (Sessions are implemented stateless with JSONWebTokens
  • Managing of user details like email address, name, avatar, preferences
  • SuperUser role

RESTful API

All features are available via a RESTful, JSON-LD inspired API and via a command line interface. API errors will always be represented as a HttpProblem.

See the BDD tests for a complete description of the API features.

The available CLI commands are defined in src/console-command/,

Besides using an EventSource connection for streaming events from the backend to the frontend, a traditional REST and JSON based implementation for reading and writing application data.

The syntax is inspired by JSON-ld which supports the discovery of API endpoints through links and adds type information to the represented data.

A client only needs to know the index for the respective API and every subsequent URL can be inferred from links in the response. The client just needs to look up the link it is interested to use.

Transferred data always contains a $context which basically gives every object a namespace. Code that is in charge of parsing responses can therefore easily validate that the data they are receiving is of the expected type.

Authorization is done stateless using JSON Web Token. It is used in HTTP request through the Authorization: Bearer … header but also through sending users links containing tokens, e.g. to reset their passwords.

The RHeactorJS DeepDive explains how this works in detail.

REST HTTP Verbs

JSON-ld does not offer a solution for describing intents in links and thus some knowledge about how to work with endpoints is not dynamically inferred but used dogmatical.

For instance, one could image the router api/user/:id/vacation which could be used with the verb PUT to set the users vacation reminder, and with the verb DELETE to disable it.

In general routes follow these rules:

  • GET: for reading entites, the server should send appropriate cache headers
  • POST: for adding entries to collections, querying search endpoints
  • PUT: for updating properties
  • DELETE: for deleting entities, deleting entity properties

API Versioning

Versioning is achieved through a custom content-type which contains a simple version number: application/vnd.acme.product.v1+json. This content type is used to configure express which essentially makes it not parse a request, if it has the wrong content-type header.

:warning: Once the version number is increased, all client request will fail, if they are running outdated code. Use this sparsely.

No batch updating of properties

The way the API endpoints are implemented serves the concept of many small updates where instead of the client being able to modify multiple properties at once, like this

PUT /api/model/10

{
  "property1": "newvalue1",
  "property2", "newvalue2"
}

it must update properties individually, like this

PUT /api/model/10/property1

{
  "value": "newvalue1"
}
PUT /api/model/10/property2

{
  "value": "newvalue2"
}

This enables all clients, and especially UI clients, to offer on-thy-fly saving of changes once the user has completed entering a new value. This greatly reduces the risk of losing changes due to connection problems or because the user forgot to click save.

UIs still may chose to offer a save feature, they can simply create all neccessary update request once the user clicks the save button.

Handling of conflicts

:information_source: Clients need to resolve conflicts

Aggregate versions play an important part in the way state changes are implemented. The server will reject any update to an entity if the a wrong version number is provided via the If-Match header.

Clients therefore need get hold of the latest version number in the server's data store. Usually this is done by reading the entity. All entites are instances of AggregateRoots or ImmutableAggregateRoots from the event-store package and provide the version number (an Integer > 0).

If an update request provides the current server version, the request will be accepted and eventually the update event persisted.

This aproach offers these advantags:

  1. Conflict handling is simple (form the servers perspective), either a change is applied fully or not, merging of changes is not supported.
  2. It's up to the UI to decide per use case if after sending a change request it should reload the whole entity, or just increment its version number for that specific entity. So that consecutive updates can be send to the server without need to re-read data. This is especially handy in situations where concurrent editing of the same entity by different users is not possible.

That means for a client (and especially for UIs), that in 99% of user updates, everything will work fine, in the rare case of a conflict, it's far easier to ask the user to "reload the page" and have the user re-apply their changes, then merging changes from different updates.

Nevertheless, for RHeactorJS applications, having real-time updates in the UI is a central feature, for which utilities have been implemented in web-app.