Flower — A little logic. A lot of bloom.

A tiny multiplayer garden.

A complete app in about 50 lines: plant seeds, watch them bloom, share the view live.

Define the data.

Each garden has twelve spots. flowers stores the seeds under [garden, id] keys; garden is a derived view that counts blooms and free spots.

Flower recomputes the view whenever a flower in that garden changes.

docs/terrarium.ts · start here

import { canonicalJson, collection, define, derive, fail, mutation, query, v } from "@flower-js/sdk";
import { scheduler } from "@flower-js/sdk/scheduler";

const GARDEN_SIZE = 12;
const name = v.string({ min: 1, max: 64 });
const flowers = collection<{ garden: string; id: string; plantedAt: number; bloomed: boolean }>("flowers")
  .key(v.tuple([name, name]))
  .index("garden", ["garden"]);

const garden = derive("garden", (ctx, id: string) => {
  const rows = ctx.query(flowers.by("garden").eq(id));
  return {
    spacesLeft: GARDEN_SIZE - rows.length,
    blooming: rows.filter((flower) => flower.bloomed).length,
    flowers: Object.fromEntries(rows.map((flower) => [flower.id, flower.bloomed ? "🌼" : "🌱"])),
  };
});
const view = query("view", { args: name, consistency: "replica-local" }, (ctx, id) => ctx.get(garden, id));

Add the methods.

plant checks its arguments against a schema, makes sure there is room, saves the seed and schedules two timers: bloom after 5 seconds, remove after 35.

Mutations run one at a time, so two gardeners can never overfill a garden. fail() tells callers why, with a code like GARDEN_FULL.

Only garden.plant and garden.view are public. Timers mean “not before”: an outage can delay them.

docs/terrarium.ts · continue the same file

const season = v.object({ key: v.tuple([name, name]), plantedAt: v.int() });
const bloom = mutation("internal.bloom", { args: season }, (ctx, event) => {
  const flower = ctx.get(flowers, event.key);
  if (flower?.plantedAt === event.plantedAt) ctx.set(flowers, event.key, { ...flower, bloomed: true });
  return null;
});
const perish = mutation("internal.perish", { args: season }, (ctx, event) => {
  if (ctx.get(flowers, event.key)?.plantedAt === event.plantedAt) ctx.delete(flowers, event.key);
  return null;
});
const seasons = scheduler("seasons", { bloom, perish });

const plant = mutation("plant", { args: v.object({ garden: name, id: name }) }, (ctx, seed) => {
  const key: [string, string] = [seed.garden, seed.id];
  if (ctx.get(flowers, key)) fail("SPOT_TAKEN", "That spot is already planted.");
  if (ctx.query(flowers.by("garden").eq(seed.garden)).length >= GARDEN_SIZE) {
    fail("GARDEN_FULL", "Garden full! Wait for a flower to make room.");
  }
  const plantedAt = ctx.now();
  ctx.set(flowers, key, { ...seed, plantedAt, bloomed: false });
  const event = { key, plantedAt }; // An old timer cannot affect a replacement.
  seasons.at(ctx, `bloom:${canonicalJson(key)}`, plantedAt + 5_000, "bloom", event);
  seasons.at(ctx, `perish:${canonicalJson(key)}`, plantedAt + 35_000, "perish", event);
  ctx.materialize(garden, seed.garden);
  return { planted: seed.id };
});

const app = define({
  uses: [seasons],
  collections: [flowers],
  definitions: [garden],
  http: { "garden.plant": plant, "garden.view": view },
});
export default app;

Call it and watch.

Plant a seed, then subscribe to the garden. Every viewer sees the same garden, and TypeScript checks every alias and argument against the app's types.

This view may lag slightly behind; drop replica-local for always-fresh reads. Anyone can plant here: add access control for private gardens.

Subscriptions show the latest state, may skip steps and reconnect on their own. Retries reuse the request ID, so a write lands once.

docs/terrarium-client.ts · outside the database

import { FlowerClient } from "@flower-js/sdk";
import type terrarium from "./terrarium.ts";

const client = new FlowerClient<typeof terrarium>("http://127.0.0.1:7101");
await client.mutate("garden.plant", { garden: "moon-garden", id: "luna" }, {
  requestId: "plant-moon-garden-luna", retry: true, // Retries reuse this ID.
});

for await (const { value } of client.subscribe("garden.view", "moon-garden")) {
  console.log(value);
  // { spacesLeft: 11, blooming: 0, flowers: { luna: "🌱" } }
  // After 5s: a bloom. After 35s: an empty spot, ready for another seed.
}

Run it yourself.

Start a local Flower node, then run these two commands from the repository.

Change the seed ID to plant another flower. Change the garden name to start a new garden.

Download the client ↓

Terminal · repository root

node sdk/cli.ts deploy docs/terrarium.ts
node docs/terrarium-client.ts

LATEST MEASURED RUN · 2026-09-25

A busy day in the garden.

Global customer calls / s: 62,061
Independent Raft groups: 8 × 3 replicas

Reads2,611,354 calls

Writes1,120,588 calls

Customer call latency, merged across groups. Each log time axis spans p0.1 to p99.9 of its calls; bar height is a bin's share of calls, and lines mark p50 and p99.

Show as a table

Customer reads, all groups
Latency	Calls	Share	Cumulative
0.0283 ms–0.0349 ms	1	<0.01%	0.00%
0.0349 ms–0.043 ms	139	0.01%	0.01%
0.043 ms–0.053 ms	1,601	0.06%	0.07%
0.053 ms–0.0653 ms	6,543	0.25%	0.32%
0.0653 ms–0.0805 ms	13,341	0.51%	0.83%
0.0805 ms–0.0992 ms	21,993	0.84%	1.67%
0.0992 ms–0.122 ms	34,873	1.34%	3.01%
0.122 ms–0.151 ms	51,365	1.97%	4.97%
0.151 ms–0.186 ms	68,728	2.63%	7.60%
0.186 ms–0.229 ms	86,159	3.30%	10.90%
0.229 ms–0.282 ms	100,506	3.85%	14.75%
0.282 ms–0.348 ms	113,987	4.37%	19.12%
0.348 ms–0.428 ms	128,873	4.94%	24.05%
0.428 ms–0.528 ms	145,762	5.58%	29.63%
0.528 ms–0.65 ms	163,989	6.28%	35.91%
0.65 ms–0.802 ms	174,942	6.70%	42.61%
0.802 ms–0.988 ms	180,542	6.91%	49.53%
0.988 ms–1.22 ms	181,556	6.95%	56.48%
1.22 ms–1.5 ms	180,561	6.91%	63.39%
1.5 ms–1.85 ms	177,887	6.81%	70.21%
1.85 ms–2.28 ms	171,516	6.57%	76.77%
2.28 ms–2.81 ms	156,215	5.98%	82.76%
2.81 ms–3.46 ms	129,894	4.97%	87.73%
3.46 ms–4.27 ms	96,899	3.71%	91.44%
4.27 ms–5.26 ms	66,935	2.56%	94.01%
5.26 ms–6.48 ms	45,684	1.75%	95.75%
6.48 ms–7.98 ms	32,973	1.26%	97.02%
7.98 ms–9.84 ms	22,264	0.85%	97.87%
9.84 ms–12.1 ms	16,596	0.64%	98.51%
12.1 ms–14.9 ms	11,921	0.46%	98.96%
14.9 ms–18.4 ms	9,069	0.35%	99.31%
18.4 ms–22.7 ms	5,802	0.22%	99.53%
22.7 ms–28 ms	3,808	0.15%	99.68%
28 ms–34.5 ms	2,643	0.10%	99.78%
34.5 ms–42.5 ms	1,512	0.06%	99.84%
42.5 ms–52.4 ms	506	0.02%	99.86%
52.4 ms–64.5 ms	274	0.01%	99.87%
64.5 ms–79.5 ms	94	<0.01%	99.87%
79.5 ms–98 ms	92	<0.01%	99.87%
98 ms–121 ms	25	<0.01%	99.87%
121 ms–149 ms	69	<0.01%	99.88%
149 ms–183 ms	127	<0.01%	99.88%
183 ms–226 ms	85	<0.01%	99.89%
226 ms–279 ms	87	<0.01%	99.89%
279 ms–343 ms	26	<0.01%	99.89%
343 ms–423 ms	91	<0.01%	99.89%
423 ms–521 ms	85	<0.01%	99.90%
521 ms–643 ms	133	0.01%	99.90%
643 ms–792 ms	95	<0.01%	99.90%
792 ms–976 ms	87	<0.01%	99.91%
976 ms–1.2 s	95	<0.01%	99.91%
1.2 s–1.48 s	5	<0.01%	99.91%
1.48 s–1.83 s	82	<0.01%	99.92%
1.83 s–2.25 s	2,217	0.08%	100%

Customer writes, all groups
Latency	Calls	Share	Cumulative
13.9 ms–14.9 ms	1	<0.01%	0.00%
14.9 ms–16 ms	2	<0.01%	0.00%
16 ms–17.2 ms	1	<0.01%	0.00%
17.2 ms–18.4 ms	3	<0.01%	0.00%
18.4 ms–19.7 ms	2	<0.01%	0.00%
19.7 ms–21.2 ms	11	<0.01%	0.00%
21.2 ms–22.7 ms	18	<0.01%	0.00%
22.7 ms–24.3 ms	28	<0.01%	0.01%
24.3 ms–26.1 ms	43	<0.01%	0.01%
26.1 ms–28 ms	73	0.01%	0.02%
28 ms–30 ms	158	0.01%	0.03%
30 ms–32.2 ms	509	0.05%	0.08%
32.2 ms–34.5 ms	910	0.08%	0.16%
34.5 ms–37 ms	1,928	0.17%	0.33%
37 ms–39.6 ms	4,036	0.36%	0.69%
39.6 ms–42.5 ms	8,435	0.75%	1.44%
42.5 ms–45.5 ms	14,154	1.26%	2.71%
45.5 ms–48.8 ms	23,959	2.14%	4.84%
48.8 ms–52.4 ms	34,853	3.11%	7.95%
52.4 ms–56.1 ms	49,036	4.38%	12.33%
56.1 ms–60.2 ms	60,789	5.42%	17.75%
60.2 ms–64.5 ms	71,006	6.34%	24.09%
64.5 ms–69.2 ms	76,451	6.82%	30.91%
69.2 ms–74.2 ms	76,603	6.84%	37.75%
74.2 ms–79.5 ms	77,598	6.92%	44.67%
79.5 ms–85.2 ms	79,005	7.05%	51.72%
85.2 ms–91.4 ms	79,026	7.05%	58.78%
91.4 ms–98 ms	76,363	6.81%	65.59%
98 ms–105 ms	70,386	6.28%	71.87%
105 ms–113 ms	67,597	6.03%	77.90%
113 ms–121 ms	63,278	5.65%	83.55%
121 ms–129 ms	54,884	4.90%	88.45%
129 ms–139 ms	40,574	3.62%	92.07%
139 ms–149 ms	27,416	2.45%	94.52%
149 ms–160 ms	19,327	1.72%	96.24%
160 ms–171 ms	14,262	1.27%	97.51%
171 ms–183 ms	7,823	0.70%	98.21%
183 ms–197 ms	5,990	0.53%	98.75%
197 ms–211 ms	4,293	0.38%	99.13%
211 ms–226 ms	2,837	0.25%	99.38%
226 ms–242 ms	2,147	0.19%	99.57%
242 ms–260 ms	1,159	0.10%	99.68%
260 ms–279 ms	1,102	0.10%	99.78%
279 ms–299 ms	104	0.01%	99.79%
299 ms–320 ms	331	0.03%	99.81%
343 ms–368 ms	61	0.01%	99.82%
368 ms–395 ms	42	<0.01%	99.82%
395 ms–423 ms	123	0.01%	99.83%
643 ms–689 ms	3	<0.01%	99.84%
689 ms–739 ms	98	0.01%	99.84%
739 ms–792 ms	202	0.02%	99.86%
792 ms–849 ms	429	0.04%	99.90%
849 ms–910 ms	880	0.08%	99.98%
910 ms–976 ms	229	0.02%	99.99%
976 ms–1.05 s	10	<0.01%	100%

Replica-local reads: lag is allowed. 70% reads / 30% mutations · HTTP/2 · 60.1 measured seconds.

Run passed. 8/8 group audits passed. 8 injected leader failures; quorum recovery 565–776 ms.

Apple M5 Pro; all replicas and load generators share one machine. Completed customer calls use the union measurement window; retries, worker traffic, and explicit replays do not inflate throughput. Reads may be stale; mutations and audits retain fresh checks.

Charts & every group →Raw measurements ↓Workload & reproduction →