THIS IS A DEPENDENCY OF freestyle-sh AND SHOULD NOT BE USED DIRECTLY

Cloudstate is a JavaScript database runtime. It is a foundational component of Freestyle's full stack JavaScript hosting.

[!TIP] Try out cloudstate via a freestyle template. Read our getting started guide to learn more.

If you're interested in learning more about how cloudstate works behind the scenes, read on.

You can install the cloudstate cli alongside the freestyle cli. Run npm install -g freestyle-sh@beta or you can build it from source.

cloudstate run ./script.js

The lowest level way to store data in cloudstate is via the cloudstate run command. You can use the global setRoot function with an id and object to store data.

const object = {
  counter: 0,
};

setRoot("test-root", object);

To retrieve an object from the database, call getRoot and pass in the identifier you used to store the object.

const object = getRoot("test-root");

If you have multiple references to the same object, those references will be preserved. The values of each property are also lazy loaded, so you don't need to worry about the complexity of objects stored in a single setRoot call.

const obj = {};
const objects = {
  a: obj,
  b: obj,
};

setRoot("objects", objects);

const objects = getRoot("objects");
objects.a === objects.b; // true

cloudstate serve ./script.js

A more structured way to store data in cloudstate is via the cloudstate serve command. Instead of writing what the script should execute, you write classes. When you put a static id on a class, it will be automatically constructed and stored using setRoot for you. Methods will be exposed as endpoints which you can call via http.

export class CounterCS {
  static id = "counter";
  count = 0;

  increment() {
    return ++this.count;
  }
}

curl -X POST http://localhost:3000/cloudstate/instances/counter/increment -H "Content-Type: application/json" -d '{"params": []}'

npx freestyle dev

The highest level api is built into freestyle's dev tooling. You can define classes anywhere in a full stack project using a decorator and they be automatically compiled into a single file and served.

import { cloudstate } from "freestyle-sh";

@cloudstate
class CounterCS {
  static id = "counter";
  count = 0;

  increment() {
    return ++this.count;
  }
}

Then you can easily query that data using useCloud.

import { type CounterCS } from "./schema.js";
import { useCloud } from "freestyle-sh";

const counter = useCloud<typeof CounterCS>("counter");

await counter.increment();

To learn more read the freestyle docs.

Contributing

• Check out the contributing guide to learn about our development process.

Building Locally

• Check out the guide for building locally to get started.

Support for JavaScript Objects

• Check out the Support for JavaScript Objects to learn more about the current state of support for JavaScript objects.