@swim/collections

@swim/collections

@swim/collections implements data structures for key-value maps and sequential lists, including B-trees and S-trees (implicitly indexed B-tree). @swim/collections is written in TypeScript, but can be used from either TypeScript or JavaScript. @swim/collections is part of the @swim/core framework.

Overview

B-trees

The BTree class implements the OrderedMap interface from @swim/util, and compares keys using Objects.compare, also from @swim/util. BTree is internally immutable, enabling lightweight snapshotting via BTree.clone, and non-destructive mutation via BTree.updated, and BTree.removed.

BTree also implements the ReducedMap interface from @swim/util, providing storage of sub-tree reductions in b-tree nodes to support log time recomputation of whole tree reductions after incremental updates.

S-trees

The STree class implements a sequential list data type that's backed by an implicitly indexed b-tree. Like BTree, STree supports lightweight snapshotting via STree.clone.

STree associated a unique ID with each list item, which can be used to reconcile concurrent, conflicting updates to the same logical list.

Installation

npm

For an npm-managed project, npm install @swim/collections to make it a dependency. TypeScript sources will be installed into node_modules/@swim/collections/main. Transpiled JavaScript and TypeScript definition files install into node_modules/@swim/collections/lib/main. And a pre-built UMD script can be found in node_modules/@swim/collections/dist/main/swim-collections.js.

Browser

Browser applications can load swim-core.js, which comes bundled with the @swim/collections library, directly from the SwimOS CDN.

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

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

Alternatively, the standalone swim-system.js script may be loaded from the SwimOS CDN, which bundles @swim/collections together with all other @swim/system libraries.

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

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

Usage

ES6/TypeScript

@swim/collections can be imported as an ES6 module from TypeScript and other ES6-compatible environments.

import * as collections from "@swim/collections";

CommonJS/Node.js

@swim/collections can also be used as a CommonJS module in Node.js applications.

var collections = require("@swim/collections");

Browser

When loaded by a web browser, the swim-core.js script adds all @swim/collections library exports to the global swim namespace.

The swim-system.js script also adds all @swim/collections library exports to the global swim namespace, making it a drop-in replacement for swim-core.js when additional @swim/system libraries are needed.