Source: https://docs.any.org/quickstart/javascript.html

# JavaScript

Everything is `fetch`. The one wrinkle is live reads: the subscribe endpoints are POSTs (the filter body does not fit a query string), so the browser's `EventSource` does not apply — you read the response body as a stream and split SSE frames yourself. The blocks below form one file: create a space and a page, keep an ordered live window over the space, rename the page while the subscription is open, and reopen the stream when it drops.

[Download client.mjs](https://docs.any.org/assets/examples/client.mjs), or copy the `js` blocks in order; they run top to bottom as an ES module (top-level `await`) in Node 18+ (`node client.mjs`) or a browser (`<script type="module">`). Each run creates a new space on the server from [Install](https://docs.any.org/quickstart/install.md.txt).

> **Note.** In a browser the server's CORS allowlist covers the desktop-shell webview origins and the Vite dev origins (`http://localhost:5173`, `http://127.0.0.1:5173`); a page served from another origin is blocked by the browser even though the server is on loopback. Serve your dev page from Vite, or proxy `/v1` through your dev server ([Security model](https://docs.any.org/operations/security-model.md.txt)).

## 1. Make an HTTP call

All ordinary calls share one helper. Keep the HTTP status even if a proxy returns an HTML or empty error body, so the reconnect loop can still recognize a temporary server failure.

```js
const API = "http://127.0.0.1:7001/v1";

async function checked(response) {
  if (response.ok) return response;
  const error = (await response.json().catch(() => null))?.error;
  throw Object.assign(new Error(`${response.status}: ${error?.message ?? response.statusText}`),
    { status: response.status, code: error?.code });
}

async function call(method, path, body, signal) {
  const response = await checked(await fetch(API + path, {
    method, signal,
    headers: body === undefined ? {} : { "content-type": "application/json" },
    body: body === undefined ? undefined : JSON.stringify(body),
  }));
  return response.status === 204 ? null : response.json();
}

const account = await call("GET", "/auth");
if (!account.authorized) throw new Error("Create or select an account before running this example.");
```

## 2. Create and read a page

A document is an object whose type has a part declaring the `editor` module — the built-in `page` for a plain body, or a document type of your own (registered as a bundle so every device agrees on one). `type` is required; `collections` is optional; `name` and `description` live in the universal `any` property group.

```js
const { id: SPACE } = await call("POST", "/spaces", { name: "JavaScript notebook" });
const { objectId } = await call("POST", `/spaces/${SPACE}/objects`, {
  type: "page", initialProperties: { any: { name: "Reading list" } },
});
const query = { filter: { "any.type": "page" }, sort: ["-modifiedAt", "id"], limit: 20 };
const page = await call("POST", `/spaces/${SPACE}/objects/query`, { ...query, includeTotal: true });
console.log("Pages:", page.total, page.records.map(r => r.any.name));
```

Expect `Pages: 1 [ 'Reading list' ]`. The query uses an explicit ascending ID as the second sort key, so equal timestamps have the same order in the server and renderer.

## 3. Read the stream

One POST returns `text/event-stream`. Parse it frame by frame: frames are separated by a blank line (LF or CRLF), each has `event:` and `data:` lines, several `data:` lines join, and `: keepalive` comments are ignored. The generator releases the reader when the loop exits.

```js
async function* sse(path, body, signal) {
  const response = await checked(await fetch(API + path, {
    method: "POST", signal,
    headers: { "content-type": "application/json", accept: "text/event-stream" },
    body: JSON.stringify(body),
  }));
  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
  let buffer = "";
  try {
    for (;;) {
      const { value, done } = await reader.read();
      if (done) return;
      buffer += value;
      let separator;
      while ((separator = /\r?\n\r?\n/.exec(buffer))) {
        const frame = buffer.slice(0, separator.index);
        buffer = buffer.slice(separator.index + separator[0].length);
        let event = "message";
        const data = [];
        for (const line of frame.split(/\r?\n/)) {
          if (line.startsWith("event:")) event = line.slice(6).trim();
          if (line.startsWith("data:")) data.push(line.slice(5).replace(/^ /, ""));
        }
        if (data.length) yield { event, data: JSON.parse(data.join("\n")) };
      }
    }
  } finally {
    try { await reader.cancel(); } catch { /* an aborted stream is already closed */ }
    reader.releaseLock();
  }
}
```

## 4. Keep a live, ordered window

A snapshot replaces the window. Deltas change membership and values; they do not reorder a JavaScript Map. Sort by the query's two keys each time you render. These object IDs are ASCII, so direct string comparison matches their byte ordering.

```js
const ctl = new AbortController();
let view = new Map();
let resolveLive, rejectLive;
const live = new Promise((resolve, reject) => { resolveLive = resolve; rejectLive = reject; });

function render() {
  const rows = [...view.values()].sort((a, b) =>
    Date.parse(b.modifiedAt.$date) - Date.parse(a.modifiedAt.$date) ||
    (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
  console.log("Live:", rows.map(r => r.any.name));
}

function pause(ms, signal) {
  return new Promise((resolve, reject) => {
    if (signal.aborted) return reject(signal.reason);
    const timer = setTimeout(() => { signal.removeEventListener("abort", abort); resolve(); }, ms);
    function abort() { clearTimeout(timer); reject(signal.reason); }
    signal.addEventListener("abort", abort, { once: true });
  });
}

async function watch() {
  const signal = ctl.signal;
  while (!signal.aborted) {
    try {
      // Check on every connection, including after EOF or a 401 without a closed frame.
      const auth = await call("GET", "/auth", undefined, signal);
      if (!auth.authorized) {
        throw Object.assign(new Error("Waiting for the original account to be authorized."), { status: 401 });
      }
      if (auth.accountId !== account.accountId) {
        view.clear(); render();
        throw Object.assign(new Error("Account changed; stopped the subscription."), { fatal: true });
      }
      for await (const { event, data } of sse(`/spaces/${SPACE}/objects/query/subscribe`, query, signal)) {
        if (event === "snapshot") {
          view = new Map(data.records.map(r => [r.id, r]));
          render(); resolveLive();
        } else if (event === "changes") {
          for (const change of data) {
            for (const row of change.added ?? []) view.set(row.id, row.doc);
            for (const row of change.updated ?? []) view.set(row.id, row.doc);
            for (const row of change.removed ?? []) view.delete(row.id);
          }
          render();
        } else if (event === "closed") {
          if (data.reason === "deauthorized") { view.clear(); render(); }
          console.log("Reopening:", data.reason);
          break;
        }
      }
    } catch (error) {
      if (error.status === 401) { view.clear(); render(); }
      if (signal.aborted || error.fatal || error instanceof SyntaxError ||
          (error.status >= 400 && error.status < 500 && ![401, 429].includes(error.status))) throw error;
      console.warn("Retrying:", error.message);
    }
    await pause(1000, signal);
  }
}
```

The loop retries network failures, server 5xx, HTTP 429, EOF and terminal frames. `closed` carries a reason — `server_shutdown`, `sdk_closed`, `overflow` (you drained too slowly), `drifted` (too much of the window left), `deauthorized` (the account was signed out or switched; read `GET /v1/auth` first). Each means the same thing for the stream: open a new POST and replace your window with the new `snapshot`. A stream that ends without `closed` means the same. There is no replay and nothing to reconcile.

While `GET /auth` reports `authorized: false`, the loop clears the view and waits. This state can occur during a restart or while a managed host authorizes an account. It subscribes again only when the original account is authorized.

A different account, cancellation, invalid JSON in a successful response or stream, or another client error stops the loop. Call `stopAnyDemo()` on deliberate sign-out: the auth status alone cannot distinguish sign-out from a temporary interruption. [Subscriptions](https://docs.any.org/realtime/subscribe.md.txt) explains each close reason and removal reason.

## 5. Rename while watching

The watcher runs concurrently. Its first snapshot releases the rename below; a failure or cancellation before that snapshot rejects the wait instead of leaving the file stuck.

```js
const stop = () => ctl.abort();
globalThis.stopAnyDemo = stop;                       // browser console: stopAnyDemo()
if (typeof process !== "undefined" && process.once) process.once("SIGINT", stop);

// Observe completion immediately, so no background rejection is left unhandled.
const finished = watch().then(() => null, error => error);
finished.then(error => rejectLive(error ?? new DOMException("Stopped", "AbortError")));

try {
  await live;
  await call("POST", `/spaces/${SPACE}/properties/${objectId}/set/any`,
    { patch: { name: "Reading list 2026" } }, ctl.signal);
  console.log("Rename saved. Leave this process open to receive further changes.");
  const error = await finished;
  if (error) throw error;
} catch (error) {
  if (error.name !== "AbortError") throw error;
} finally {
  stop();
  await finished;
  delete globalThis.stopAnyDemo;
  if (typeof process !== "undefined" && process.removeListener) process.removeListener("SIGINT", stop);
}
```

Expect the live output to contain `Reading list 2026`. Stop with Ctrl-C in Node, or `stopAnyDemo()` in the browser console. The object remains in the space.

## Writing and reading back

Object creation returns `objectId`. Dataset writes, chat messages included, return `{versionId, changeId, recordIds}` and never the record. Read it back through a query, or let the open subscription deliver it — stamp `versionId` on what you wrote if you need to recognise your own change on the stream ([Best practices](https://docs.any.org/understanding/best-practices.md.txt)); it is not a version to compare across devices.

A chat uses the same pattern: install `general-chat` through `POST /catalog/general-chat/setup`, take `bundles[0].bundle.rootId`, and send to `POST /spaces/:spaceId/objects/:chatId/chat/messages`. [Python](https://docs.any.org/quickstart/python.md.txt#3-read-a-dataset) shows the complete dataset write and pagination sequence.

Next: [Reading data](https://docs.any.org/database/reading-data.md.txt), [Python](https://docs.any.org/quickstart/python.md.txt), or [the tutorial](https://docs.any.org/tutorial/index.md.txt).