Getting Started

Swim is a full stack streaming application platform for building stateful services, streaming APIs, and real-time UIs. Streaming applications push differential state changes through the full application stack, eliminating the need for polling and streaming only what each client chooses to observe. Real-time UIs render live views of distributed application state.

Creating a real-time UI starts with WARP Client, a streaming API client for consuming multiplexed streaming APIs. It opens links to lanes of stateful Web Agents using the WARP protocol, enabling massively real-time applications that continuously synchronize all shared states with half ping latency. The client requires no configuration and makes opening links to Web Agents a cinch. It is UI framework-agnostic and works in both browser and Node.js runtime environments.

Installation

To begin using WARP client, install the @swim/client package.

NPM

npm install @swim/client

CDN

<!-- Development -->
<script src="https://cdn.swimos.org/js/4.0.0/swim.js"></script>

<!-- Production -->
<script src="https://cdn.swimos.org/js/4.0.0/swim.min.js"></script>

Usage

NPM

Exports of @swim/client may be imported as ES modules in ES2015-compatible environments. You may also import modules from a number of other Swim libraries installed as dependencies of @swim/client. A notable example of this is @swim/structure which we will see referenced in later sections.

import { WarpClient } from "@swim/client";
import { Value } from "@swim/structure";

Browser / CDN

The swim.js script bundles exports from @swim/client, its Swim dependencies, and a number of additional Swim libraries useful for building real time UIs, including tools for making charts and maps. When loaded by a web browser, the swim.js script adds all library exports to the global swim namespace.

const client = new swim.WarpClient();

TypeScript

Typescript definition files are provided in the libraries.

All downlink variants support the ability to provide type information for incoming and outgoing WARP messages. The exception to this is EventDownlink, which should rarely be used. See our article on Forms for more details and an example of how to provide downlinks with type information.

Quick Start

Connecting to a lane of a remote Web Agent with the WARP client can be done in just a few lines.

Import and initialize an instance of WarpClient.

import { WarpClient } from "@swim/client";

const client = new WarpClient();

Next, create a link for connecting to your remote Web Agent.

const downlink = client.downlink();

Then provide your link with the nodeUri and `laneUri of the Web Agent to which you wish to connect.

downlink.setHostUri("warp://example.com");
downlink.setNodeUri("/myAgent");
downlink.setLaneUri("someLane");

And define a callback for handling messages received by the link.

downlink.onEvent = (value) => {
  const userCount = `${value.stringValue("0")} Users`;
  document.getElementById("active-user-count").innerText = userCount;
};

Finally, open your downlink.

downlink.open();

Once the downlink is open, events should begin streaming into the application. Whether they arrive as a trickle or a flood, applications may use these messages to update UI views and other dependent components, keeping them consistent with the shared state of the remote Web Agent in network real-time.