TypeScript API

Spaces

A space is an instance of an ECHO database which can be replicated by a number of peers.

This section describes how to create, join, and invite peers to ECHO Spaces with the TypeScript API.

Creating spaces

Having established an identity, a space can be created:

import { Client } from '@dxos/client';

const client = new Client();
await client.initialize();

// Ensure an identity exists.
if (!client.halo.identity.get()) {
  await client.halo.createIdentity();
}

// Create a space.
const _space = await client.spaces.create();

Listing spaces

Obtain a list of Space objects:

import { Client } from '@dxos/client';

const client = new Client();
await client.initialize();

// Get a list of all spaces.
const _spaces = client.spaces.get();

Creating an invitation

See ECHO Spaces for a description of the way peers join spaces.

import { Client } from '@dxos/client';
import { InvitationEncoder } from '@dxos/client/invitations';

const client = new Client();
await client.initialize();

// Ensure an identity exists.
if (!client.halo.identity.get()) {
  await client.halo.createIdentity();
}

// Create a space.
const space = await client.spaces.create();

// Create an invitation to join the space.
const invitation = space.share();

// Share this code with a friend, it will be used to locate the peer and
// establish a secure connection.
const _code = InvitationEncoder.encode(invitation.get());

// Later we will pass this second authentication code to our friend over a
// side-channel and they'll send it to us over the new connection which
// will verify that it's secure.
const _authCode = invitation.get().authCode;

Accepting invitations

See ECHO Spaces for a description of the way peers join spaces.

import { Client } from '@dxos/client';
import { InvitationEncoder } from '@dxos/client/invitations';

const client = new Client();
await client.initialize();

// Ensure an identity exists.
if (!client.halo.identity.get()) {
  await client.halo.createIdentity();
}

// Friend decodes the invitation code.
const receivedInvitation = InvitationEncoder.decode('<invitation code here>');

// Accept the invitation.
const invitation = client.spaces.join(receivedInvitation);

// Verify it's secure by sending the second factor authCode.
await invitation.authenticate('<authentication code here>');

// Space joined!
const _space = client.spaces.get(invitation.get().spaceKey!);

Having obtained a space, it is now possible to query and mutate objects in that space.