Tutorial 1 - Creating Sources and Clients
We're making a chat app, but we need to save and sync our data. Our "Sources" define where the data is saved, and how it is connected to the app.
Our First Source
For testing, we could save our data in memory only. In production we should connect to a real database like Postgres. But for now, let's save our app data as files.
We also need to invent a "domain" to use, a named bucket for your app's data to live in. Because we're creating a chat app, lets use "chat.aven.io"
import startFSDataSource from '@aven-cloud/cloud-fs/startFSDataSource';
const source = await startFSStorageSource({
domain: 'chat.aven.io', // our new domain
dataDir: './db', // the path of where the files will be stored
});
Great! Now we can call "source.dispatch" to send actions for saving and retrieving data. See the full Source API Spec here.
Note: The FS storage will work fine as long as you only run one server against it at a time. If you want to run multiple servers in front of a single storage mechanism, use a postgres storage source.
Over the Network
Our node.js program needs to serve the data to the web client or native app that runs on the user's device. So we can take our storage source and expose it over the network with a server:
import startSourceServer from '@aven-cloud/cloud-server/startSourceServer';
const server = await startSourceServer({
source,
listenLocation: 3000,
});
Once this resolves, the Source will be accessible at http://localhost:3000
Then from the client, we can connect to the Source Server:
import createBrowserNetworkSource from '@aven-cloud/cloud-browser/createBrowserNetworkSource';
const source = await createBrowserNetworkSource({
authority: 'localhost:3000',
useSSL: false
});
Now, the source on the client will have the same behavior as the one on the server, allowing us to save data.
Create a Cloud Client
The source API is meant to be easily transmitted over a network, but it is inconvenient to use. A client will be useful for hydrating data from the source, observing it, and making mutations that appear to be reflected immediately.
Once we have any Source, we can create a "cloud" client to consume data within a specified domain:
import createCloudClient from '@aven-cloud/cloud/createCloudClient';
const cloud = await createCloudClient({
source,
domain: 'chat.aven.io'
});
Now we can use the client to conveniently write data to the database:
const chatRoom = cloud.get('ChatRoom');
// save a new JSON object to the ChatRoom doc:
await chatRoom.put({ messages: ['Hello'] });
Any other client connected to the same Source can access the value as such:
const chatRoom = cloud.get('ChatRoom');
// fetch and log the current value of the ChatRoom doc:
await chatRoom.fetchValue();
console.log(chatRoom.getValue());