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();
(async () => {
  await client.initialize();
  // ensure an identity exists:
  if (!client.halo.identity.get()) await client.halo.createIdentity();
  // create a space:
  const space = await client.createSpace();
})();

Listing spaces

Obtain a list of Space objects:

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

const client = new Client();

(async () => {
  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, InvitationEncoder } from '@dxos/client';

const client = new Client();

(async () => {
  await client.initialize();
  // ensure an identity exists
  if (!client.halo.identity.get()) await client.halo.createIdentity();
  // create a space
  const space = await client.createSpace();
  // create an invitation to join the space
  const invitation = space.createInvitation();
  // 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, InvitationEncoder } from '@dxos/client';

const client = new Client();

(async () => {
  await client.initialize();
  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.acceptInvitation(receivedInvitation);
  // verify it's secure by sending the second factor authCode
  await invitation.authenticate('<authentication code here>');
  // space joined!
  const space = client.getSpace(invitation.get().spaceKey!);
})();

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