Client and transports.

FlowerClient

Use FlowerClient to call your methods from Node or a browser. Point it at any cluster member.

import { FlowerClient, FlowerError } from "@flower-js/sdk/client";

const db = new FlowerClient("http://node-1:7101", {
  queryUrls: ["http://node-1:7101", "http://node-2:7101", "http://node-3:7101"],
});
const requestId = crypto.randomUUID(); // Persist before sending.
try {
  await db.mutate("orders.save", { id: "42", cents: 900 }, { requestId });
} catch (error) {
  if (error instanceof FlowerError) console.error(error.status, error.code);
  // After an uncertain response, retry the same body and requestId.
}

Retrying safely

• A timed-out or lost mutation may still have committed. Retry with the same request ID, arguments and expected revision. Save the request ID before sending.
• Same ID, different body: REQUEST_ID_REUSED. Stale expected revision: REVISION_CONFLICT. Server queue full: 503.
• Aborting stops waiting. It doesn’t undo a commit.
• Old request IDs never run again, even after their results are dropped. See retry retention.
• The SDK doesn’t retry or fail over for you. If a member is unreachable, try another one yourself.

Watches

A watch streams a query’s latest value as it changes, over SSE.

import { FlowerClient } from "@flower-js/sdk/client";

const db = new FlowerClient("http://node-1:7101");
const stop = new AbortController();
for await (const { revision, value } of db.watch("pizza.board", null, { signal: stop.signal })) {
  console.log(revision, value);
  // break or stop.abort() releases the subscription.
}

• A watch gives you the latest value, not every change. Intermediate revisions can be skipped. It isn’t an event log.
• Fresh watches read like fresh queries. Replica-local watches can lag, and can go back in time after reconnecting elsewhere.
• Watches don’t reconnect. After an error or abort, start a new watch and expect a new snapshot.
• A redeploy or change of caller identity ends the stream with WATCH_SCOPE_CHANGED. Malformed stream data ends it with WATCH_PROTOCOL_ERROR.
• Break the loop or abort the signal to close the stream.
• Each subscriber is authorized on every refresh. Remember that one watched value can combine data from many records.
• There’s no fixed limit on watch count. Memory, sockets and update rate set the practical limit. Slow consumers get batched updates and are eventually closed.

HTTP/2 transport

In Node, use one pooled HTTP/2 transport to share connections across many requests and watches.

import { FlowerClient } from "@flower-js/sdk/client";
import { createHttp2Transport } from "@flower-js/sdk/http2";

const transport = createHttp2Transport();
try {
  const db = new FlowerClient("http://localhost:7101", { fetch: transport.fetch });
  console.log(await db.query("pizza.board"));
} finally {
  await transport.close();
}

• The request timeout covers the whole response, except for SSE, where it covers only the headers.
• No HTTP/1 fallback, redirects, retries or compressed responses.
• Transport failures throw errors with H2_* codes. After a connection failure, a mutation’s outcome is unknown, so retry it with the same request ID.