# @swim/client > Streaming API client for linking to lanes of stateful Web Agents using the WARP protocol, enabling massively real-time applications that continuously synchronize all shared states with ping latency Latest version **4.0.0** (published 2024-06-09) · Apache-2.0 license · 0 weekly downloads ## Install ```sh npm install @swim/client pnpm add @swim/client yarn add @swim/client bun add @swim/client ``` Provides the command `swim-client`. ## Health **Score 30/100 (F)** — status: abandoned. Positive: has types; esm support; no vulnerabilities; high quality score. Warnings: low downloads. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 4.0.0 | | Published | 2024-06-09 | | First published | 2018-01-25 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 11 | | Unpacked size | 3.3 MB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | Chris Sachs | | Maintainers | cwjames19, ajay-gov, c9r | | Keywords | client, protocol, recon, swim, warp, webagent, websocket | ## Links - npm: https://www.npmjs.com/package/@swim/client - Repository: https://github.com/swimos/swim-js - Homepage: https://github.com/swimos/swim-js/tree/main/swim-host/swim-client - Issues: https://github.com/swimos/swim-js/issues - npm.io page: https://npm.io/package/@swim/client ## Dependencies (11) - [ws](https://npm.io/package/ws.md) 8 - [tslib](https://npm.io/package/tslib.md) >= 2.5 - [@swim/uri](https://npm.io/package/@swim/uri.md) 4.0.0 - [@swim/args](https://npm.io/package/@swim/args.md) 4.0.0 - [@swim/util](https://npm.io/package/@swim/util.md) 4.0.0 - [@swim/warp](https://npm.io/package/@swim/warp.md) 4.0.0 - [@swim/codec](https://npm.io/package/@swim/codec.md) 4.0.0 - [@swim/recon](https://npm.io/package/@swim/recon.md) 4.0.0 - [@swim/component](https://npm.io/package/@swim/component.md) 4.0.0 - [@swim/structure](https://npm.io/package/@swim/structure.md) 4.0.0 - [@swim/collections](https://npm.io/package/@swim/collections.md) 4.0.0 ## Alternatives - [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads - [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads - [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads - [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads - [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads ## Recent versions - 4.0.0 (latest) — 2024-06-09 - 4.0.0-dev.20240413 (dev) — 2024-04-13 - 4.0.0-dev.20210927.3 — 2024-04-04 - 4.0.0-dev.20230923 — 2023-09-23 - 4.0.0-dev.20220527.3 — 2022-05-27 - 4.0.0-dev.20220527.2 — 2022-05-27 - 4.0.0-dev.20220527.1 — 2022-05-27 - 4.0.0-dev.20220527 — 2022-05-27 - 4.0.0-dev.20210927.2 — 2021-11-11 - 4.0.0-dev.20210927.1 — 2021-09-27 - 4.0.0-dev.20210927 — 2021-09-27 - 4.0.0-dev.20210923 — 2021-09-23 - 4.0.0-dev.20210920 — 2021-09-20 - 4.0.0-dev.20210826 — 2021-08-26 - 3.11.1 — 2021-08-17 - … 24 more at https://npm.io/package/@swim/client/versions ## README # [![Swim](https://docs.swimos.org/readme/breach-marlin-blue-wide.svg)](https://www.swimos.org) Swim Client Library The Swim Client library implements a streaming API client for linking to lanes of stateful Web Agents using the multiplxed WARP streaming protocol. Command line tool for linking to Web Agent lanes over the WARP protocol. ## Installation ```sh npm install -g swim-client ``` ## Command Line ```sh $ swim-client help Usage: swim-client Commands: link stream changes to a lane of a remote node sync stream the current state and changes to a lane of a remote node get fetch the current state of a lane of a remote node reflect stream introspection metadata help ``` ```sh $ swim-client sync help Usage: swim-client sync [options] Options: -h, --host remote host to link -n, --node remote node to link -l, --lane lane to link -f, --format event output format Commands: help ``` ```sh $ swim-client reflect help Usage: swim-client reflect [options] Options: -e, --edge endpoint to introspect -m, --mesh ? introspect default or specified mesh -p, --part ? introspect default or specified partition -h, --host ? introspect default or specified host -n, --node introspect specified node -l, --lane introspect specified lane -k, --link introspect link behavior -r, --router introspect router behavior --data introspect data behavior --system introspect system behavior --process introspect process behavior -s, --stats stream introspection statistics -f, --format event output format Commands: log stream log events help ``` ## API ### WarpRef A `WarpRef` is a handle through which WARP downlinks can be opened. `WarpClient` implements the `WarpRef` interface, as does the exported Swim Client module object, and by extension, the global `swim` namespace object used web browsers and other non-module contexts. `WarpRef` instances have four methods that open different kinds of downlinks. The `downlink` method creates an `EventDownlink` for streaming raw events from any Web Agent lane. The `valueDownlink` method creates a `ValueDownlink` for synchronizing state with a Web Agent value lane. The `mapDownlink` method creates a `MapDownlink` for synchronizing state with a Web Agent map lane. And the `listDownlink` method creates a `ListDownlink` for synchronizing state with a Web Agent list lane. ```typescript swim.downlink() .hostUri("warp://traffic.swim.services") .nodeUri("swim:meta:mesh") .laneUri("linkStats") .onEvent((value) => console.log(value.toLike())) .open(); ``` `WarpRef` instances can also be used to observe key lifecycle events. The `WarpRef.didConnect` method registers an observer callback that gets invoked whenever a connection to a WARP host is establishes. The `WarpRef.didDisconnect` method registers an observer callback that gets invoked whenever a WARP host disconnects. `WarpRef.didAuthenticate` registers an observer callback that gets invoked whenever the client successfully authenticates with a WARP host. `WarpRef.didDeauthenticate` gets invoked when a WARP host rejects the client's authentication credentials. And the `WarpRef.didFail` method registers an observer callback that gets invoked when the client encounters an unexpected error. ```typescript swim.didConnect((host) => console.log("connected to", host)); swim.didDisconnect((host) => console.log("disconnected from", host)); swim.didAuthenticate((session, host) => console.log("authenticated to", host, "with session", session.toLike())); swim.didDeauthenticate((reason, host) => console.log("deauthenticated from", host, "because", reason.toLike())); swim.didFail((error, host) => console.log("host", host, "failed because", error)); ``` ### WarpClient The `WarpClient` class handles connection management and link routing, and implements the `WarpRef` interface. In addition to opening downlinks, `WarpClient` instances can be used to send arbitrary WARP commands, to provide authentication credentials for hosts, to control network reconnection behavior, and to create `HostRef`, `NodeRef`, and `LaneRef` scopes to facilitate downlink management. The `WarpClient.authenticate` method associates a credentials structure with a particular host URI. The credentials will be sent in a WARP `@auth` envelope whenever the client connects to the specified host. ```typescript swim.authenticate("warps://example.com", {"@openId": jwt}); ``` Distinct `WarpClient` instances can be used to create isolated connection pools for different security domains. ```typescript const userClient = new WarpClient(); userClient.authenticate("warps://example.com", {"@openId": userJwt}); const toolClient = new WarpClient(); toolClient.authenticate("warps://example.com", {"@oauth": toolJwt}); ``` The `WarpClient.command` method sends a WARP command message to a lane of a remote node. `WarpClient.command` takes either three our four arguments. The three argument `command` overload takes a node URI, a lane URI, and a command payload. The node URI must have an authority component that specifies the host to which the command should be sent. The four argument `command` overload takes a host URI, a node URI, a lane URI, and a command payload; the node URI is interpreted relative to the host URI. ```typescript swim.command("warp://example.com/house/kitchen", "light", "on"); swim.command("warp://example.com", "/house/kitchen", "light", "off"); ``` The `WarpClient.isOnline` method returns `true` when the the client has access to a network; it can also be used to force a client online or offline. The `WarpClient.keepOnline` method controls whether or not the client should automatically reopen connections after a network failure. Note that the `keepOnline` state of the client overrides the `keepLinked` state of individual downlinks. Setting `keepOnline` to false can be useful for ephemeral clients, but should typically be left `true`. ```typescript swim.isOnline(); // true most of the time swim.isOnline(false); // force offline swim.isOnline(true); // force online swim.keepOnline(); // defaults to true swim.keepOnline(false); // disable network reconnection ``` The `WarpClient.hostRef` method returns a new `HostRef` bound to the given host URI. The `WarpClient.nodeRef` method returns a new `NodeRef` bound to the given host and node URIs. The `WarpClient.laneRef` method returns a new `LaneRef` bound to the given host, node, and lane URIs. ### HostRef A `HostRef` is a `WarpRef` that automatically provides its bound host URI when opening downlinks, sending commands, and providing authentication credentials. `HostRef` instances keep track of all the downlinks they directly open. When a `HostRef` is closed, it automatically closes all of its open downlink views. ```typescript const hostRef = swim.hostRef("warp://traffic.swim.services"); hostRef.downlink() .nodeUri("swim:meta:mesh") .laneUri("linkStats") .onEvent((value) => console.log(value.toLike())}) .open(); // ... hostRef.close(); ``` The `HostRef.nodeRef` and `HostRef.laneRef` instance methods can be used to create further resolved `WarpRef` scopes. ```typescript const hostRef = swim.hostRef("warp://traffic.swim.services"); const nodeRef = hostRef.nodeRef("swim:meta:mesh"); const laneRef = hostRef.laneRef("swim:meta:mesh", "linkStats"); ``` ### NodeRef A `NodeRef` is a `WarpRef` that automatically provides its bound host and node URIs when opening downlinks and sending commands. `NodeRef` instances keep track of all the downlinks they directly open. When a `NodeRef` is closed, it automatically closes all of its open downlink views. ```typescript const nodeRef = swim.nodeRef("warp://traffic.swim.services", "swim:meta:mesh"); nodeRef.downlink() .laneUri("linkStats") .onEvent((value) => console.log(value.toLike())}) .open(); // ... nodeRef.close(); ``` The `NodeRef.laneRef` instance method can be used to create further resolved `WarpRef` scopes. ```typescript const nodeRef = swim.nodeRef("warp://traffic.swim.services", "swim:meta:mesh"); const laneRef = nodeRef.laneRef("linkStats"); ``` ### LaneRef A `LaneRef` is a `WarpRef` that automatically provides its bound host, node, and lane URIs when opening downlinks and sending commands. `LaneRef` instances keep track of all the downlinks they directly open. When a `LaneRef` is closed, it automatically closes all of its open downlink views. ```typescript const laneRef = swim.laneRef("warp://traffic.swim.services", "swim:meta:mesh", "linkStats"); laneRef.downlink() .onEvent((value) => console.log(value.toLike())}) .open(); // ... laneRef.close(); ``` ### Downlink A `Downlink` provides a virtual bidirectional stream between the client and a lane of a remote Web Agent. WARP clients transparently multiplex all links to Web Agents on a given host over a single WebSocket connection, and automatically manage the network connection to each host, including reconnection and resynchronization after a network failure. WARP clients also seamlessly handle multicast event routing when multiple downlinks are opened to the same lane of the same remote Web Agent. Downlinks come in several flavors, depending on the WARP subprotocol to which they conform. An `EventDownlink` observes raw WARP events, and can be used to observe lanes of any kind. A `ValueDownlink` synchronizes a structured value with a remote value lane. A `MapDownlink` implements the WARP map subprotocol to synchronize key-value state with a remote map lane. A `ListDownlink` implements the WARP list subprotocol to to synchronize sequential list state with a remote list lane. Before opening, a downlink must be addressed with the `hostUri`, `nodeUri`, and `laneUri` to which the link should connect. A downlink may also be configured with a relative `prio`rity, a max `rate`, and an optional `body` structure that can contain query or other link parameters to be passed to the remote lane. The `keepLinked` parameter determines whether or not a downlink should be automatically reopened after a network failure; it defaults to `true`. The `keepSynced` parameter determines whether or not a downlink should synchronize with the remote lane when opened; it defaults to `true` for stateful lanes. The `open` method is used to open a downlink after it has been configured. The `close` method closes a downlink. Closing a downlink does not necessarily close the underlying WARP link. The WARP client will keep a link open so long as at least one downlink to a given node and lane URI remains open. This prevents application components from stepping on each other's toes when they link to the same lanes of the same Web Agents. This can happen, for example, when a UI has a summary view and a detail view both display information derived from the same remote lane. The WARP link should not be closed when a detail view is hidden, if state updates are still required by the summary view. Events should also not be sent twice: once for the summary view, and once for the detail view. Neither the summary view nor the detail view should have to know about each other. And no global event dispatcher should be required, which could introduce consistency problems. WARP clients efficiently, and transparently handle all of these cases on behalf of all downlinks. The `isConnected` method returns `true` if the underlying connection to the remote host is currently open. The `isAuthenticated` method returns `true` if the underlying connection to the remote host is currently authenticated. The `isLinked` method returns `true` if the logical WARP link is currently open. And the `isSynced` method returns `true` if the WARP link is currently synchronized. All downlinks support registering `onEvent`, `onCommand`, `willLink`, `didLink`, `willSync`, `didSync`, `willUnlink`, `didUnlink`, `willConnect`, `didConnect`, `didDisconnect`, `didClose`, and `didFail` callbacks. ### EventDownlink An `EventDownlink` provides a raw view of a WARP link. ```typescript swim.downlink() .hostUri("warp://example.com") .nodeUri("/house") .laneUri("power/meter") .onEvent((body) => /* ... */) .open(); ``` ### ValueDownlink A `ValueDownlink` synchronizes a shared real-time value with a remote value lane. In addition to the standard `Downlink` callbacks, `ValueDownlink` supports registering `willSet` and `didSet` callbacks to observe all changes to downlinked state—whether remote or local. A `ValueDownlink` views its state as an [Swim Structure][structure] `Value` by default. Use the `valueForm` method to create a typed projection of a `ValueDownlink` that automatically transforms its state using an Swim Structure `Form`. For example, you can use `Form.foString()` to create a `ValueDownlink` that coerces its state to a string; and you can also use `Form.forAny()` to create a `ValueDownlink` that coerces its state to a plain old JavaScript value. ```typescript const value = swim.downlinkValue() .hostUri("warp://example.com") .nodeUri("/house/kitchen") .laneUri("light") .valueForm(swim.Form.forAny()) .didSet((value) => /* ... */) .open(); ``` Use the `ValueDownlink.get` method to get the current state value. Use the `ValueDownlink.set` method to set the current state value. ```typescript value.get(); // get the current local state of the downlink value.set(newValue); // update the local and remote state of the downlink ``` For the most part, client code can treat a `ValueDownlink` like an ordinary mutable variable; the WARP client will ensure that the downlink is continuously made consistent with the remote lane. Using `didSet` callbacks, applications can update UI views, and other dependent components, to keep them consistent with the shared state of the remote value lane in network real-time. ```typescript swim.downlinkValue() .didSet((value) => { // update UI view with latest value document.getElementById("value").innerText = value; }) ``` ### MapDownlink A `MapDownlink` synchronizes a shared real-time key-value map with a remote map lane. In addition to the standard `Downlink` callbacks, `MapDownlink` supports registering `willUpdate`, `didUpdate`, `willRemove`, and `didRemove` callbacks to observe all changes to downlinked map state—whether remote or local. A `MapDownlink` views its keys and values as [Swim Structure][structure] `Value`s by default. Use the `keyForm` and `valueForm` methods to create a typed projection of a `MapDownlink` that automatically transforms its keys and values using Swim Structure `Form`s. ```typescript const map = swim.downlinkMap() .hostUri("warp://example.com") .nodeUri("/house") .laneUri("rooms") .keyForm(swim.Form.forString()) .valueForm(swim.Form.forAny()) .didUpdate((key, value) => /* ... */) .didRemove((key) => /* ... */) .open(); ``` `MapDownlink` implements the standard JavaScript `Map` interface. Use the `MapDownlink.get` method to get the value associated with a given key. Use the `MapDownlink.set` method to update the value associated with a key. And use the `MapDownlink.delete` method to remove a key and its associated value. ```typescript map.get("kitchen"); // get the locally cached value associated with the key map.set("garage", newRoom); // locally and remotely insert a new entry ``` For the most part, client code can treat a `MapDownlink` like an ordinary JavaScript `Map`; the WARP client will ensure that the downlink is continuously made consistent with the remote lane. Using `didUpdate` and `didRemove` callbacks, applications can update UI collection views, and other dependent components, to keep them consistent with the shared state of the remote map lane in network real-time. ```typescript swim.downlinkMap() .didUpdate((key, value) => { if (hasChildElement(key)) { // update existing UI view for key } else { // insert new UI view for key } }) .didRemove((key) => { // remove UI view for key }) ``` ### ListDownlink A `ListDownlink` synchronizes a shared real-time list with a remote list lane. In addition to the standard `Downlink` callbacks, `ListDownlink` supports registering `willUpdate`, `didUpdate`, `willMove`, `didMove`, `willRemove`, and `didRemove` callbacks to observe all changes to downlinked list state—whether remote or local. A `ListDownlink` views its items as [Swim Structure][structure] `Value`s by default. Use the `valueForm` method to create a typed projection of a `ListDownlink` that automatically transforms its items using an Swim Structure `Form`. ```typescript const list = swim.downlinkList() .hostUri("warp://example.com") .nodeUri("/house") .laneUri("todo") .valueForm(swim.Form.forAny()) .didUpdate((index, value) => /* ... */) .didMove((fromIndex, toIndex, value) => /* ... */) .didRemove((index) => /* ... */) .open(); ``` `ListDownlink` behaves similarly to a JavaScript array. Use the `ListDownlink.get` method to get the item at a given index. Use the `ListDownlink.set` method to update the item at some index. And use the `ListDownlink.splice` method to insert and remove items from the list. You can also `push`, `pop`, `shift`, and `unshift` items, and `move` an item from one index to another. ```typescript list.get(0); // get the first item in the list list.set(0, "build"); // locally and remotely update an item list.push("paint"); // locally and remotely append an item ``` For the most part, client code can treat a `ListDownlink` like an ordinary JavaScript list; the WARP client will ensure that the downlink is continuously made consistent with the remote lane. Using `didUpdate`, `didMove`, and `didRemove` callbacks, applications can update UI list views, and other dependent components, to keep them consistent with the shared state of the remote list lane in network real-time. ```typescript swim.downlinkList() .didUpdate((index, value) => { if (hasChildElement(index)) { // update existing UI view at index } else { // insert new UI view at index } }) .didMove((fromIndex, toIndex, value)) { // move existing UI view from old index to new index } .didRemove((index) => { // remove UI view at index }) ``` [structure]: swim-core/@swim/structure --- _Source: https://npm.io/package/@swim/client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._