@nano133/nanoterra 0.5.0 → 0.6.0

package/dist/admin/panel/mount.js

@@ -28,7 +28,7 @@ export function mountAdmin(root, options) {
     let game = null;
     let gameState = null;
     let dash = null;
-    /** The card, made once. A fault in reading the two switches must not hide the orders: the card is left out and the rest still shows. */
+    /** The card, made once. A fault in reading the game switches must not hide the orders: the card is left out and the rest still shows. */
     async function gameSection() {
         if (game)
             return game;

package/dist/admin/panel/overview.d.ts

@@ -16,7 +16,7 @@ export declare function bestSellers(s: Pick<AdminSummary, "orders" | "players">,
 export type OverviewView = {
     el: HTMLElement;
     update(s: AdminSummary): void;
-    /** The two switches as they are now (null: they could not be read). */
+    /** The game switches as they are now (null: they could not be read). */
     setGame(state: GameState | null): void;
 };
 export declare function overviewView(looks: readonly Look[], colourOf: (lookId: string) => string | null, go: (tab: TabId, filter?: OrderFilter) => void): OverviewView;

package/dist/admin/panel/overview.js

@@ -1,7 +1,7 @@
 // The Overview tab of /admin: the game at a glance. The best-selling looks with their share of the money, the last five orders, the two game switches as On or
 // Off, and the shelf in numbers; each part has a key to its own tab. A game with no sale yet gets three first steps instead of empty lists.
 import { priceText } from "../../looks/ladder.js";
-import { SWITCHES, stateOf } from "../switches.js";
+import { FRIENDS_CHOICES, FRIENDS_TITLE, SWITCHES, stateOf } from "../switches.js";
 import { dollars, h, plural } from "./dom.js";
 import { icon } from "./icons.js";
 import { orderRow } from "./orders.js";
@@ -35,7 +35,9 @@ export function overviewView(looks, colourOf, go) {
             const on = game ? stateOf(id, game) : null;
             return h("li", {}, h("span", {}, SWITCHES[id].title), on === null ? h("span", { class: "pill" }, "Unknown") : h("span", { class: `pill ${on ? "pill-on" : "pill-off"}` }, on ? "On" : "Off"));
         });
-        gameBox.replaceChildren(h("div", { class: "card-head" }, h("h2", { id: "n133-glance-game" }, "Game switches"), linkKey("Change", () => go("settings"))), game ? h("ul", { class: "glance-list" }, ...rows) : h("p", { class: "fine" }, "The two switches could not be read. Reload the page to try again."));
+        if (game)
+            rows.push(h("li", {}, h("span", {}, FRIENDS_TITLE), h("span", { class: `pill ${game.friends === "off" ? "pill-off" : "pill-on"}` }, FRIENDS_CHOICES[game.friends]?.name ?? "Unknown")));
+        gameBox.replaceChildren(h("div", { class: "card-head" }, h("h2", { id: "n133-glance-game" }, "Game switches"), linkKey("Change", () => go("settings"))), game ? h("ul", { class: "glance-list" }, ...rows) : h("p", { class: "fine" }, "The game switches could not be read. Reload the page to try again."));
     }
     function drawShelf() {
         const sale = looks.filter((l) => l.priceUsd > 0);

package/dist/admin/store.d.ts

@@ -71,7 +71,7 @@ export type AdminLogin = {
 /** How many sign-ins the panel lists. */
 export declare const ADMIN_LOGINS_SHOWN = 10;
 /**
- * The game's database, as the handler needs it. An adapter writes ONLY what these calls say: the two settings and, when the game turns it on, the deletion of the admin sessions
+ * The game's database, as the handler needs it. An adapter writes ONLY what these calls say: the three settings and, when the game turns it on, the deletion of the admin sessions
  * (`signOutEverywhere`). Nothing else.
  * (There is no call that writes a look, a price or an order: the Shelf gives text to copy, and a change of looks is a change of the repository.)
  */
@@ -80,6 +80,7 @@ export interface AdminStore {
     readSettings(): Promise<{
         character?: unknown;
         signin?: unknown;
+        friends?: unknown;
     }>;
     /** Saves a checked patch: all of it or none of it. */
     saveSettings(patch: GamePatch, now: number): Promise<void>;

package/dist/admin/switches.d.ts

@@ -2,25 +2,40 @@
 export type Character = "nanoterra" | "own";
 /** How the game signs a Nanoterra player in: the code exchange, a signed ticket (a game with no server), or not at all. */
 export type Signin = "exchange" | "ticket" | "none";
+/**
+ * Which friends list the game shows: Nanoterra's (the nano133 window, "@nano133/nanoterra/friends/panel"), the game's own (its own players and store), or none.
+ * A three-way choice, not an On/Off switch.
+ */
+export type Friends = "nanoterra" | "own" | "off";
+/** The game's own words for the switches. `friends` may be left out: it is "nanoterra" then (on by default). */
 export type GameSettings = {
     character: Character;
     signin: Signin;
+    friends?: Friends;
 };
 /** What a press can set: sign-in is on ("exchange": a game with a server) or off ("none"). */
 export type GamePatch = {
     character?: Character;
     signin?: "exchange" | "none";
+    friends?: Friends;
 };
 /** The settings as they are now, and which ones /admin has set (the others still have the game's default). */
-export type GameState = GameSettings & {
+export type GameState = {
+    character: Character;
+    signin: Signin;
+    friends: Friends;
     fromAdmin: {
         character: boolean;
         signin: boolean;
+        friends: boolean;
     };
 };
 export declare const isCharacter: (v: unknown) => v is Character;
 export declare const isSigninChoice: (v: unknown) => v is "exchange" | "none";
 export declare const isSignin: (v: unknown) => v is Signin;
+export declare const isFriends: (v: unknown) => v is Friends;
+/** The friends list a game shows while neither its own words nor /admin say: Nanoterra's. */
+export declare const DEFAULT_FRIENDS: Friends;
 /** The sign-in switch is on for any way but "none". */
 export declare const signinOn: (s: Signin) => boolean;
 /** A request body for a press: only the two known words, at least one. Anything else is refused, with the reason in words. */
@@ -35,7 +50,14 @@ export declare function parsePatch(body: unknown): {
 export declare function mergeSettings(stored: {
     character?: unknown;
     signin?: unknown;
+    friends?: unknown;
 }, defaults: GameSettings): GameState;
+/** The friends choice of the card: its title, and for each choice its short name (the card's three keys) and one plain sentence. Nanoterra's is the default. */
+export declare const FRIENDS_TITLE = "Friends list";
+export declare const FRIENDS_CHOICES: Record<Friends, {
+    name: string;
+    note: string;
+}>;
 /** One switch of the card: its title, and one plain sentence for each state. */
 export type SwitchId = "character" | "signin";
 export declare const SWITCHES: Record<SwitchId, {

package/dist/admin/switches.js

@@ -1,20 +1,27 @@
-// The two switches of the "Game" card in /admin, and the words that say what each does. The handler checks a press with `parsePatch`; the panel
-// draws the card from `SWITCHES`. A switch changes ONLY these two settings; never a look, a price or an order.
+// The switches of the "Game" card in /admin, and the words that say what each does. The handler checks a press with `parsePatch`; the panel
+// draws the card from `SWITCHES` and `FRIENDS_CHOICES`. A switch changes ONLY these three settings; never a look, a price or an order.
 export const isCharacter = (v) => v === "nanoterra" || v === "own";
 export const isSigninChoice = (v) => v === "exchange" || v === "none";
 export const isSignin = (v) => v === "exchange" || v === "ticket" || v === "none";
+export const isFriends = (v) => v === "nanoterra" || v === "own" || v === "off";
+/** The friends list a game shows while neither its own words nor /admin say: Nanoterra's. */
+export const DEFAULT_FRIENDS = "nanoterra";
 /** The sign-in switch is on for any way but "none". */
 export const signinOn = (s) => s !== "none";
 /** A request body for a press: only the two known words, at least one. Anything else is refused, with the reason in words. */
 export function parsePatch(body) {
     if (!body || typeof body !== "object" || Array.isArray(body))
-        return { ok: false, error: 'Send an object with "character" or "signin".' };
+        return { ok: false, error: 'Send an object with "character", "signin" or "friends".' };
     const patch = {};
     for (const [key, value] of Object.entries(body)) {
         if (key === "character" && isCharacter(value))
             patch.character = value;
         else if (key === "signin" && isSigninChoice(value))
             patch.signin = value;
+        else if (key === "friends" && isFriends(value))
+            patch.friends = value;
+        else if (key === "friends")
+            return { ok: false, error: '"friends" must be "nanoterra", "own" or "off".' };
         else if (key === "character")
             return { ok: false, error: '"character" must be "nanoterra" or "own".' };
         else if (key === "signin")
@@ -23,7 +30,7 @@ export function parsePatch(body) {
             return { ok: false, error: `"${key}" is not a game switch.` };
     }
     if (!Object.keys(patch).length)
-        return { ok: false, error: 'Send "character" or "signin".' };
+        return { ok: false, error: 'Send "character", "signin" or "friends".' };
     return { ok: true, patch };
 }
 /** The settings from what the store kept and the game's defaults. A stored value that is not one of the known words is ignored. */
@@ -31,9 +38,23 @@ export function mergeSettings(stored, defaults) {
     return {
         character: isCharacter(stored.character) ? stored.character : defaults.character,
         signin: isSigninChoice(stored.signin) ? stored.signin : defaults.signin,
-        fromAdmin: { character: isCharacter(stored.character), signin: isSigninChoice(stored.signin) },
+        friends: isFriends(stored.friends) ? stored.friends : isFriends(defaults.friends) ? defaults.friends : DEFAULT_FRIENDS,
+        fromAdmin: { character: isCharacter(stored.character), signin: isSigninChoice(stored.signin), friends: isFriends(stored.friends) },
     };
 }
+/** The friends choice of the card: its title, and for each choice its short name (the card's three keys) and one plain sentence. Nanoterra's is the default. */
+export const FRIENDS_TITLE = "Friends list";
+export const FRIENDS_CHOICES = {
+    nanoterra: {
+        name: "Nanoterra",
+        note: "Nanoterra: a player signed in on nano133 sees their Nanoterra friends in a small nano133 frame in your game, and their friends see that they are playing it. The friends stay on nano133: your game gets none of them.",
+    },
+    own: {
+        name: "The game's own",
+        note: "The game's own: a friends list of this game's players, kept in this game's own database. Nanoterra friends do not show.",
+    },
+    off: { name: "Off", note: "Off: the game shows no friends list." },
+};
 export const SWITCHES = {
     character: {
         title: "Players can play as their Nanoterra character",

package/dist/friends/adapters/d1.d.ts

@@ -0,0 +1,4 @@
+import type { D1Like } from "../../admin/adapters/d1.js";
+import { type FriendsStore } from "../types.js";
+export type { D1Like, D1StatementLike } from "../../admin/adapters/d1.js";
+export declare function createD1Friends(db: D1Like): FriendsStore;

package/dist/friends/adapters/d1.js

@@ -0,0 +1,131 @@
+// The friends store for a game on Cloudflare D1. The tables are in ./d1.sql (the package ships it: "@nano133/nanoterra/friends/d1.sql"); add it to
+// the game's migrations. It reads and writes ONLY friend_edges, friend_presence and friend_prefs.
+//
+//   import { createD1Friends } from "@nano133/nanoterra/friends/d1";
+//   const friends = createD1Friends(env.DB);
+//
+// D1 has no transaction that reads and then writes, so each write is ONE statement that holds its own check: a change of an edge says which `rev`
+// it read (a row that changed in between is not written, and the player is asked to try again), and a new edge is written only while both players
+// have room (the count is in the same statement) and the pair has no row yet (UNIQUE (a, b)).
+import { buildRows, checkPulse, pairOf, planAccept, planBlock, planDecline, planInvite, planRemove, planRequest, planUnblock, shownOthers } from "../rules.js";
+import { FRIEND_LIMIT, FRIEND_REQUEST_MS, FriendsError } from "../types.js";
+const COLS = "edge, a, b, from_player, state, blocked_by, at, invite_from, invite_where, invite_at, rev";
+function recOf(r) {
+    let blockedBy = [];
+    try {
+        const v = JSON.parse(r.blocked_by);
+        if (Array.isArray(v))
+            blockedBy = v.filter((x) => typeof x === "string");
+    }
+    catch {
+        blockedBy = [];
+    }
+    const state = r.state === "friend" || r.state === "blocked" ? r.state : "pending";
+    const invite = typeof r.invite_from === "string" && typeof r.invite_where === "string" && typeof r.invite_at === "number" ? { from: r.invite_from, where: r.invite_where, at: Number(r.invite_at) } : null;
+    return { edge: r.edge, a: r.a, b: r.b, from: r.from_player, state, blockedBy, at: Number(r.at), invite, rev: Number(r.rev) };
+}
+const CHANGED = "That changed just now. Try again.";
+export function createD1Friends(db) {
+    const changes = (res) => Number(res?.meta?.changes ?? 0);
+    const byEdge = async (edge) => {
+        const r = await db.prepare(`SELECT ${COLS} FROM friend_edges WHERE edge = ?`).bind(edge).first();
+        return r ? recOf(r) : null;
+    };
+    const byPair = async (x, y) => {
+        const [a, b] = pairOf(x, y);
+        const r = await db.prepare(`SELECT ${COLS} FROM friend_edges WHERE a = ? AND b = ?`).bind(a, b).first();
+        return r ? recOf(r) : null;
+    };
+    /** Live edges of a player, as SQL (?1 the player, ?2 the oldest request time that still counts). */
+    const LIVE_COUNT = "(SELECT COUNT(*) FROM friend_edges WHERE (a = ?1 OR b = ?1) AND (state != 'pending' OR at > ?2))";
+    const liveCount = async (player, now) => Number((await db.prepare(`SELECT ${LIVE_COUNT} AS n`).bind(player, now - FRIEND_REQUEST_MS).first())?.n ?? 0);
+    async function apply(plan, prev, now) {
+        if ("none" in plan)
+            return;
+        if ("drop" in plan) {
+            if (changes(await db.prepare("DELETE FROM friend_edges WHERE edge = ? AND rev = ?").bind(plan.drop.edge, plan.drop.rev).run()) !== 1)
+                throw new FriendsError(409, CHANGED);
+            return;
+        }
+        const r = plan.put;
+        const inv = r.invite;
+        if (prev && prev.edge === r.edge) {
+            const res = await db
+                .prepare("UPDATE friend_edges SET from_player = ?, state = ?, blocked_by = ?, at = ?, invite_from = ?, invite_where = ?, invite_at = ?, rev = ? WHERE edge = ? AND rev = ?")
+                .bind(r.from, r.state, JSON.stringify(r.blockedBy), r.at, inv?.from ?? null, inv?.where ?? null, inv?.at ?? null, r.rev, r.edge, prev.rev)
+                .run();
+            if (changes(res) !== 1)
+                throw new FriendsError(409, CHANGED);
+            return;
+        }
+        // A new edge: only while both players have room, in the same statement (the pair's UNIQUE (a, b) refuses a second row).
+        const cut = now - FRIEND_REQUEST_MS;
+        const other = r.from === r.a ? r.b : r.a;
+        const sql = `INSERT INTO friend_edges (${COLS}) SELECT ?3, ?4, ?5, ?6, ?7, ?8, ?9, NULL, NULL, NULL, ?10 ` +
+            `WHERE (SELECT COUNT(*) FROM friend_edges WHERE (a = ?1 OR b = ?1) AND (state != 'pending' OR at > ?11)) < ?12 ` +
+            `AND (SELECT COUNT(*) FROM friend_edges WHERE (a = ?2 OR b = ?2) AND (state != 'pending' OR at > ?11)) < ?12 ` +
+            `ON CONFLICT (a, b) DO NOTHING`;
+        const res = await db.prepare(sql).bind(r.from, other, r.edge, r.a, r.b, r.from, r.state, JSON.stringify(r.blockedBy), r.at, r.rev, cut, FRIEND_LIMIT).run();
+        if (changes(res) !== 1)
+            throw new FriendsError(409, CHANGED);
+    }
+    async function onEdge(_player, edge, plan, now) {
+        const rec = await byEdge(edge);
+        await apply(plan(rec), rec, now);
+    }
+    return {
+        async view(player, directory, now) {
+            const recs = (await db.prepare(`SELECT ${COLS} FROM friend_edges WHERE a = ?1 OR b = ?1`).bind(player).all()).results.map(recOf);
+            // The presence and the choice of the player's friends, in one statement each (a friend's id is the other side of a friend edge).
+            const OTHER = "CASE WHEN e.a = ?1 THEN e.b ELSE e.a END";
+            const pres = (await db
+                .prepare(`SELECT p.player, p.place, p.lease, p.at FROM friend_edges e JOIN friend_presence p ON p.player = ${OTHER} WHERE (e.a = ?1 OR e.b = ?1) AND e.state = 'friend'`)
+                .bind(player)
+                .all()).results;
+            const hidden = (await db.prepare(`SELECT f.player FROM friend_edges e JOIN friend_prefs f ON f.player = ${OTHER} WHERE (e.a = ?1 OR e.b = ?1) AND e.state = 'friend' AND f.show_online = 0`).bind(player).all()).results;
+            const me = await db.prepare("SELECT show_online FROM friend_prefs WHERE player = ?").bind(player).first();
+            const names = await directory.names(shownOthers(player, recs, now));
+            const presence = new Map(pres.map((p) => [p.player, { player: p.player, where: p.place, lease: p.lease, at: Number(p.at) }]));
+            const shows = new Map(hidden.map((x) => [x.player, false]));
+            return { showOnline: !me || Number(me.show_online) !== 0, people: buildRows(player, recs, now, names, presence, shows) };
+        },
+        async request(player, other, now) {
+            const rec = await byPair(player, other);
+            const plan = await planRequest(player, other, rec, now, async () => ({ mine: await liveCount(player, now), theirs: await liveCount(other, now) }));
+            // A request that went stale is still the pair's row: it is changed in place (its count is the one just read).
+            await apply(plan, rec, now);
+        },
+        accept: (player, edge, now) => onEdge(player, edge, (r) => planAccept(player, r, now), now),
+        decline: (player, edge) => onEdge(player, edge, (r) => planDecline(player, r, Date.now()), Date.now()),
+        remove: (player, edge) => onEdge(player, edge, (r) => planRemove(player, r, Date.now()), Date.now()),
+        block: (player, edge, now) => onEdge(player, edge, (r) => planBlock(player, r, now), now),
+        unblock: (player, edge, now) => onEdge(player, edge, (r) => planUnblock(player, r, now), now),
+        invite: (player, edge, where, now) => onEdge(player, edge, (r) => planInvite(player, r, where, now), now),
+        async pulse(player, where, lease, now) {
+            const p = checkPulse(where, lease);
+            if (p.where !== null) {
+                await db
+                    .prepare("INSERT INTO friend_presence (player, place, lease, at) VALUES (?, ?, ?, ?) ON CONFLICT (player) DO UPDATE SET place = excluded.place, lease = excluded.lease, at = excluded.at")
+                    .bind(player, p.where, p.lease, now)
+                    .run();
+                return;
+            }
+            // Leaving: only the tab that holds the row may clear it (planPulse's rule, in the statement).
+            await db.prepare("DELETE FROM friend_presence WHERE player = ? AND lease = ?").bind(player, p.lease).run();
+        },
+        async setShowOnline(player, on) {
+            const stmts = [db.prepare("INSERT INTO friend_prefs (player, show_online) VALUES (?, ?) ON CONFLICT (player) DO UPDATE SET show_online = excluded.show_online").bind(player, on ? 1 : 0)];
+            if (!on)
+                stmts.push(db.prepare("DELETE FROM friend_presence WHERE player = ?").bind(player));
+            await db.batch(stmts);
+        },
+        async forget(player) {
+            const done = await db.batch([
+                db.prepare("DELETE FROM friend_edges WHERE a = ?1 OR b = ?1").bind(player),
+                db.prepare("DELETE FROM friend_presence WHERE player = ?").bind(player),
+                db.prepare("DELETE FROM friend_prefs WHERE player = ?").bind(player),
+            ]);
+            return done.reduce((n, r) => n + changes(r), 0);
+        },
+    };
+}

package/dist/friends/adapters/firestore.d.ts

@@ -0,0 +1,49 @@
+import { type FriendsStore } from "../types.js";
+export type FriendsDocSnap = {
+    exists: boolean;
+    data(): Record<string, unknown> | undefined;
+};
+export interface FriendsDocRef {
+    get(): Promise<FriendsDocSnap>;
+}
+export type FriendsQuerySnap = {
+    docs: {
+        id: string;
+        ref: FriendsDocRef;
+        data(): Record<string, unknown>;
+    }[];
+};
+export interface FriendsQuery {
+    where(field: string, op: "==" | "array-contains", value: unknown): FriendsQuery;
+    limit(n: number): FriendsQuery;
+    get(): Promise<FriendsQuerySnap>;
+}
+export interface FriendsCollection extends FriendsQuery {
+    doc(id: string): FriendsDocRef;
+}
+/** A transaction: every read before the first write, as Firestore asks. */
+export interface FriendsTransaction {
+    get(ref: FriendsDocRef): Promise<FriendsDocSnap>;
+    get(query: FriendsQuery): Promise<FriendsQuerySnap>;
+    set(ref: FriendsDocRef, data: Record<string, unknown>): unknown;
+    delete(ref: FriendsDocRef): unknown;
+}
+export interface FriendsBatch {
+    set(ref: FriendsDocRef, data: Record<string, unknown>, options?: {
+        merge?: boolean;
+    }): unknown;
+    delete(ref: FriendsDocRef): unknown;
+    commit(): Promise<unknown>;
+}
+export interface FirestoreFriendsLike {
+    collection(name: string): FriendsCollection;
+    runTransaction<T>(fn: (tx: FriendsTransaction) => Promise<T>): Promise<T>;
+    batch(): FriendsBatch;
+}
+/** How many edges of one player a read takes at most: the limit, the blocks by others and old requests fit under it. */
+export declare const FIRESTORE_FRIENDS_SCAN = 1000;
+export declare function createFirestoreFriends(db: FirestoreFriendsLike, collections?: {
+    edges?: string;
+    presence?: string;
+    prefs?: string;
+}): FriendsStore;

package/dist/friends/adapters/firestore.js

@@ -0,0 +1,163 @@
+// The friends store for a game on Firestore (the Admin SDK). The package has no Firebase dependency: the adapter uses the small interface below,
+// which the Admin SDK's `Firestore` fits. It reads and writes ONLY its three collections.
+//
+//   import { createFirestoreFriends } from "@nano133/nanoterra/friends/firestore";
+//   const friends = createFirestoreFriends(getFirestore());
+//
+// The data model (the three collection names can be changed):
+//   friend_edges/{pair}       { edge, a, b, players: [a, b], from, state, blockedBy, at, invite: { from, where, at } | null, rev }
+//   friend_presence/{player}  { player, where, lease, at }
+//   friend_prefs/{player}     { player, showOnline }
+// `{pair}` and `{player}` are SHA-256 hex digests (of "a\u0000b" and of the player's id), so any id makes a valid document id, and a pair has one
+// document: two requests at the same moment meet on it in their transactions. `edge` is a random id; the browser sees only that.
+// Indexes: the single-field indexes Firestore makes by itself are enough (`players` array-contains, `edge` ==).
+import { buildRows, checkPulse, friendsOf, hasPlayer, liveEdge, pairOf, planAccept, planBlock, planDecline, planInvite, planPulse, planRemove, planRequest, planUnblock, shownOthers } from "../rules.js";
+import { FriendsError } from "../types.js";
+/** How many edges of one player a read takes at most: the limit, the blocks by others and old requests fit under it. */
+export const FIRESTORE_FRIENDS_SCAN = 1000;
+async function sha256(text) {
+    const bytes = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+const text = (v, fallback = "") => (typeof v === "string" ? v : fallback);
+const num = (v, fallback = 0) => (typeof v === "number" && Number.isFinite(v) ? v : fallback);
+function recOf(d) {
+    const inv = d.invite;
+    const state = d.state === "friend" || d.state === "blocked" ? d.state : "pending";
+    return {
+        edge: text(d.edge),
+        a: text(d.a),
+        b: text(d.b),
+        from: text(d.from),
+        state,
+        blockedBy: Array.isArray(d.blockedBy) ? d.blockedBy.filter((x) => typeof x === "string") : [],
+        at: num(d.at),
+        invite: inv && typeof inv.from === "string" && typeof inv.where === "string" && typeof inv.at === "number" ? { from: inv.from, where: inv.where, at: inv.at } : null,
+        rev: num(d.rev),
+    };
+}
+const dataOf = (r) => ({ edge: r.edge, a: r.a, b: r.b, players: [r.a, r.b], from: r.from, state: r.state, blockedBy: r.blockedBy, at: r.at, invite: r.invite, rev: r.rev });
+export function createFirestoreFriends(db, collections = {}) {
+    const edges = () => db.collection(collections.edges ?? "friend_edges");
+    const presenceCol = () => db.collection(collections.presence ?? "friend_presence");
+    const prefsCol = () => db.collection(collections.prefs ?? "friend_prefs");
+    const pairRef = async (x, y) => {
+        const [a, b] = pairOf(x, y);
+        return edges().doc(await sha256(`${a}\u0000${b}`));
+    };
+    const playerRef = async (col, player) => col.doc(await sha256(player));
+    const ofPlayer = (player) => edges().where("players", "array-contains", player).limit(FIRESTORE_FRIENDS_SCAN);
+    /** Writes a plan in the transaction, on the pair's document. */
+    async function write(tx, plan) {
+        if ("none" in plan)
+            return;
+        const rec = "put" in plan ? plan.put : plan.drop;
+        const ref = await pairRef(rec.a, rec.b);
+        if ("put" in plan)
+            tx.set(ref, dataOf(plan.put));
+        else
+            tx.delete(ref);
+    }
+    /** An operation on an edge the browser named: the edge is found, then read again in the transaction on its pair's document. */
+    async function onEdge(player, edge, plan) {
+        const found = await edges().where("edge", "==", edge).limit(2).get();
+        const first = found.docs.map((d) => recOf(d.data())).find((r) => hasPlayer(r, player));
+        if (!first) {
+            plan(null);
+            return;
+        }
+        const ref = await pairRef(first.a, first.b);
+        await db.runTransaction(async (tx) => {
+            const snap = await tx.get(ref);
+            const now = snap.exists ? recOf(snap.data() ?? {}) : null;
+            // The pair's document holds another edge now (it was removed and asked again): the old edge is gone.
+            await write(tx, plan(now && now.edge === edge ? now : null));
+        });
+    }
+    const liveOf = (snap, now) => snap.docs.map((d) => recOf(d.data())).filter((r) => liveEdge(r, now)).length;
+    return {
+        async view(player, directory, now) {
+            const recs = (await ofPlayer(player).get()).docs.map((d) => recOf(d.data())).filter((r) => hasPlayer(r, player));
+            const friends = friendsOf(player, recs, now);
+            const [mePref, pres, prefs, names] = await Promise.all([
+                (await playerRef(prefsCol(), player)).get(),
+                Promise.all(friends.map(async (f) => (await playerRef(presenceCol(), f)).get())),
+                Promise.all(friends.map(async (f) => (await playerRef(prefsCol(), f)).get())),
+                directory.names(shownOthers(player, recs, now)),
+            ]);
+            const presence = new Map();
+            pres.forEach((s, i) => {
+                const d = s.exists ? s.data() : undefined;
+                if (d && d.player === friends[i])
+                    presence.set(friends[i], { player: friends[i], where: text(d.where), lease: text(d.lease), at: num(d.at) });
+            });
+            const shows = new Map();
+            prefs.forEach((s, i) => {
+                const d = s.exists ? s.data() : undefined;
+                if (d && d.player === friends[i] && d.showOnline === false)
+                    shows.set(friends[i], false);
+            });
+            const mine = mePref.exists ? mePref.data() : undefined;
+            return { showOnline: mine?.showOnline !== false, people: buildRows(player, recs, now, names, presence, shows) };
+        },
+        async request(player, other, now) {
+            if (player === other)
+                throw new FriendsError(400, "You cannot add yourself.");
+            const ref = await pairRef(player, other);
+            await db.runTransaction(async (tx) => {
+                const snap = await tx.get(ref);
+                const rec = snap.exists ? recOf(snap.data() ?? {}) : null;
+                // The counts are read in the transaction too (every read before the first write).
+                const plan = await planRequest(player, other, rec, now, async () => {
+                    const [mine, theirs] = await Promise.all([tx.get(ofPlayer(player)), tx.get(ofPlayer(other))]);
+                    return { mine: liveOf(mine, now), theirs: liveOf(theirs, now) };
+                });
+                await write(tx, plan);
+            });
+        },
+        accept: (player, edge, now) => onEdge(player, edge, (r) => planAccept(player, r, now)),
+        decline: (player, edge) => onEdge(player, edge, (r) => planDecline(player, r, Date.now())),
+        remove: (player, edge) => onEdge(player, edge, (r) => planRemove(player, r, Date.now())),
+        block: (player, edge, now) => onEdge(player, edge, (r) => planBlock(player, r, now)),
+        unblock: (player, edge, now) => onEdge(player, edge, (r) => planUnblock(player, r, now)),
+        invite: (player, edge, where, now) => onEdge(player, edge, (r) => planInvite(player, r, where, now)),
+        async pulse(player, where, lease, now) {
+            const p = checkPulse(where, lease);
+            const ref = await playerRef(presenceCol(), player);
+            await db.runTransaction(async (tx) => {
+                const snap = await tx.get(ref);
+                const d = snap.exists ? snap.data() : undefined;
+                const was = d ? { player, where: text(d.where), lease: text(d.lease), at: num(d.at) } : null;
+                const plan = planPulse(player, p.where, p.lease, was, now);
+                if ("put" in plan)
+                    tx.set(ref, { player, where: plan.put.where, lease: plan.put.lease, at: plan.put.at });
+                else if ("drop" in plan)
+                    tx.delete(ref);
+            });
+        },
+        async setShowOnline(player, on) {
+            const batch = db.batch();
+            batch.set(await playerRef(prefsCol(), player), { player, showOnline: Boolean(on) });
+            if (!on)
+                batch.delete(await playerRef(presenceCol(), player));
+            await batch.commit();
+        },
+        async forget(player) {
+            const docs = (await ofPlayer(player).get()).docs.filter((d) => hasPlayer(recOf(d.data()), player));
+            const [pres, pref] = await Promise.all([(await playerRef(presenceCol(), player)).get(), (await playerRef(prefsCol(), player)).get()]);
+            const refs = docs.map((d) => d.ref);
+            if (pres.exists)
+                refs.push(await playerRef(presenceCol(), player));
+            if (pref.exists)
+                refs.push(await playerRef(prefsCol(), player));
+            // A batch holds at most 500 writes.
+            for (let i = 0; i < refs.length; i += 400) {
+                const batch = db.batch();
+                for (const ref of refs.slice(i, i + 400))
+                    batch.delete(ref);
+                await batch.commit();
+            }
+            return refs.length;
+        },
+    };
+}

package/dist/friends/conformance.d.ts

@@ -0,0 +1,11 @@
+import { type FriendsStore } from "./types.js";
+export type FriendsHarness = {
+    store: FriendsStore;
+    /** Every row the store keeps (edges, presence, prefs) as one text. `forget` must leave none that holds the player's id. */
+    dump(): Promise<string>;
+};
+export type FriendsConformanceCase = {
+    name: string;
+    run: () => Promise<void>;
+};
+export declare function friendsStoreConformance(make: () => Promise<FriendsHarness>): FriendsConformanceCase[];