@carlonicora/nextjs-jsonapi 6.12.1 → 6.13.0

package/src/offline/__tests__/offline-fixtures.ts

@@ -0,0 +1,89 @@
+import { configureOffline, resetOfflineConfig, setDeviceStoreOpener } from "../config";
+import { resetOfflineState } from "../state";
+import type { DeviceStore } from "../store/DeviceStore";
+import { openMemoryDeviceStore } from "../store/lifecycle";
+import type { OfflineConfig, OfflineRoute } from "../types";
+
+export class TestModel {
+  id = "";
+  name = "";
+  rehydrate(data: { jsonApi: any }) {
+    this.id = data.jsonApi.id;
+    this.name = data.jsonApi.attributes?.name ?? "";
+    return this;
+  }
+}
+
+export const Roots = { name: "roots", model: TestModel };
+export const Npcs = { name: "npcs", model: TestModel };
+export const Factions = { name: "factions", model: TestModel };
+export const Characters = { name: "characters", model: TestModel };
+
+export const npc = (id: string, name: string, rootId: string) => ({
+  type: "npcs",
+  id,
+  attributes: { name, description: `${name} text` },
+  relationships: { root: { data: { type: "roots", id: rootId } } },
+});
+
+export function offlineConfig(routes: OfflineRoute[] = []): OfflineConfig {
+  return {
+    getUserId: () => "u1",
+    rootModule: Roots,
+    types: [
+      { module: Roots, fetch: "by-id", readOnly: false, serverOwnedFields: [] },
+      { module: Npcs, fetch: "root-list", readOnly: false, serverOwnedFields: ["tldr"] },
+      { module: Factions, fetch: "root-list", readOnly: false, serverOwnedFields: [] },
+      { module: Characters, fetch: "root-list", readOnly: true, serverOwnedFields: [] },
+    ],
+    routes,
+    listSyncRoots: async () => ["C", "D"],
+    shellPath: () => "/offline-shell",
+    syncIntervalMs: 300000,
+  };
+}
+
+/** Two NPCs and a faction in root record C, one NPC in D; the faction is linked to n1. */
+export async function seededStore(): Promise<DeviceStore> {
+  const store = await openMemoryDeviceStore();
+  await store.putRecord({
+    type: "roots",
+    id: "C",
+    rootId: "C",
+    resource: { type: "roots", id: "C", attributes: { name: "Camp C" } },
+    updatedAt: null,
+  });
+  await store.putRecord({ type: "npcs", id: "n1", rootId: "C", resource: npc("n1", "Alda", "C"), updatedAt: null });
+  await store.putRecord({ type: "npcs", id: "n2", rootId: "C", resource: npc("n2", "brom", "C"), updatedAt: null });
+  await store.putRecord({ type: "npcs", id: "n3", rootId: "D", resource: npc("n3", "Cora", "D"), updatedAt: null });
+  await store.putRecord({
+    type: "factions",
+    id: "f1",
+    rootId: "C",
+    resource: { type: "factions", id: "f1", attributes: { name: "Guild" } },
+    updatedAt: null,
+  });
+  await store.putRecord({
+    type: "characters",
+    id: "ch1",
+    rootId: "C",
+    resource: { type: "characters", id: "ch1", attributes: { name: "Hero" } },
+    updatedAt: null,
+  });
+  await store.putLink({ fromType: "factions", fromId: "f1", toType: "npcs", toId: "n1", kind: "MEMBER_OF", props: {} });
+  return store;
+}
+
+export async function setUpOffline(routes: OfflineRoute[] = []): Promise<DeviceStore> {
+  resetOfflineState();
+  resetOfflineConfig();
+  const store = await seededStore();
+  configureOffline(offlineConfig(routes));
+  setDeviceStoreOpener(async () => store);
+  return store;
+}
+
+export function tearDownOffline(): void {
+  resetOfflineConfig();
+  resetOfflineState();
+}

package/src/offline/__tests__/router.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { matchRoute } from "../router";
+import type { OfflineRoute } from "../types";
+import { patternToString } from "../types";
+
+const Npcs = { name: "npcs", model: class {} };
+const Roots = { name: "roots", model: class {} };
+const answer = (label: string) => async () => ({ status: 200, body: { label } });
+
+describe("matchRoute", () => {
+  it("custom routes win over generic ones", async () => {
+    const custom: OfflineRoute = {
+      method: "GET",
+      pattern: [Roots, ":id", "scenes", "playing"],
+      answer: answer("custom"),
+      queue: false,
+    };
+    const generic: OfflineRoute = {
+      method: "GET",
+      pattern: [":parentType", ":parentId", "scenes", ":x"],
+      answer: answer("generic"),
+      queue: false,
+    };
+
+    const match = matchRoute([custom, generic], "GET", "roots/C/scenes/playing");
+
+    expect(match?.route).toBe(custom);
+  });
+
+  it("a Module segment matches its endpoint", () => {
+    const route: OfflineRoute = { method: "GET", pattern: [Npcs, ":id"], answer: answer("one"), queue: false };
+
+    expect(matchRoute([route], "GET", "npcs/n1")?.params).toEqual({ id: "n1" });
+    expect(matchRoute([route], "GET", "factions/n1")).toBeNull();
+    expect(patternToString([Roots, ":id", Npcs])).toBe("roots/:id/npcs");
+  });
+
+  it(":id captures one segment", () => {
+    const route: OfflineRoute = { method: "GET", pattern: [Npcs, ":id"], answer: answer("one"), queue: false };
+
+    expect(matchRoute([route], "GET", "npcs/n1/factions")).toBeNull();
+    expect(matchRoute([route], "GET", "npcs")).toBeNull();
+    expect(matchRoute([route], "PATCH", "npcs/n1")).toBeNull();
+  });
+
+  it("the query string is ignored for matching", () => {
+    const route: OfflineRoute = {
+      method: "GET",
+      pattern: [Roots, ":id", Npcs],
+      answer: answer("list"),
+      queue: false,
+    };
+
+    expect(matchRoute([route], "GET", "roots/C/npcs?fetchAll=true&page[size]=5")?.params).toEqual({ id: "C" });
+  });
+});

package/src/offline/__tests__/state.spec.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { configureOffline, resetOfflineConfig } from "../config";
+import { getOfflineState, resetOfflineState, setOfflineState, subscribeOfflineState } from "../state";
+import type { OfflineConfig } from "../types";
+
+const config: OfflineConfig = {
+  getUserId: () => "u1",
+  rootModule: { name: "roots", model: class {} },
+  types: [],
+  routes: [],
+  listSyncRoots: async () => [],
+  shellPath: () => "/offline-shell",
+  syncIntervalMs: 300000,
+};
+
+describe("offline state", () => {
+  beforeEach(() => {
+    resetOfflineState();
+    resetOfflineConfig();
+  });
+
+  afterEach(() => {
+    resetOfflineState();
+    resetOfflineConfig();
+  });
+
+  it("the offline event marks the session offline; the online event alone never brings it back (a probe or a sync must reach the API)", () => {
+    configureOffline(config);
+    expect(getOfflineState().online).toBe(true);
+
+    window.dispatchEvent(new Event("offline"));
+    expect(getOfflineState().online).toBe(false);
+
+    window.dispatchEvent(new Event("online"));
+    expect(getOfflineState().online).toBe(false);
+  });
+
+  it("does not follow browser events when offline mode is not configured", () => {
+    window.dispatchEvent(new Event("offline"));
+    expect(getOfflineState().online).toBe(true);
+  });
+
+  it("listeners are called once per change", () => {
+    const listener = vi.fn();
+    const unsubscribe = subscribeOfflineState(listener);
+
+    setOfflineState({ pending: 2 });
+    setOfflineState({ pending: 2 });
+    setOfflineState({ lockedRootIds: ["C"] });
+    setOfflineState({ lockedRootIds: ["C"] });
+    setOfflineState({ online: false, draining: false });
+
+    expect(listener).toHaveBeenCalledTimes(3);
+    expect(listener).toHaveBeenLastCalledWith(
+      expect.objectContaining({ online: false, pending: 2, lockedRootIds: ["C"] }),
+    );
+
+    unsubscribe();
+    setOfflineState({ pending: 3 });
+    expect(listener).toHaveBeenCalledTimes(3);
+  });
+});

package/src/offline/__tests__/write-through.spec.ts

@@ -0,0 +1,137 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { DeviceStore } from "../store/DeviceStore";
+import { artwork, fakeCacheStorage, npc, setUpSync, tearDownSync } from "../sync/__tests__/sync-fixtures";
+import { markOfflineUnavailable, OfflineUnavailableError } from "../config";
+import { writeThrough } from "../write-through";
+
+const ok = (data: any) => ({ ok: true, status: 200, statusText: "OK", data });
+
+describe("writeThrough", () => {
+  let store: DeviceStore;
+  let cache: ReturnType<typeof fakeCacheStorage>;
+
+  beforeEach(async () => {
+    store = await setUpSync();
+    // The device keeps root record C (its root record is stored).
+    await store.putRecord({
+      type: "roots",
+      id: "C",
+      rootId: "C",
+      resource: { type: "roots", id: "C", attributes: { name: "C" } },
+      updatedAt: null,
+    });
+    cache = fakeCacheStorage(["wyrdli-offline-1", "wyrdli-images"]);
+    vi.stubGlobal("caches", cache.storage);
+  });
+
+  afterEach(() => {
+    tearDownSync();
+    vi.unstubAllGlobals();
+  });
+
+  it("stores the answer of an online write", async () => {
+    await writeThrough({ method: "PATCH", url: "http://api.test/npcs/n1" }, ok({ data: npc("n1", "Saved") }));
+
+    expect((await store.getRecord("npcs", "n1"))?.resource.attributes.name).toBe("Saved");
+  });
+
+  it("in a browser that cannot keep the device copy, stores nothing and logs nothing per request", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    markOfflineUnavailable(new OfflineUnavailableError("the browser offers no private file storage"));
+    warn.mockClear();
+
+    await writeThrough({ method: "PATCH", url: "http://api.test/npcs/n1" }, ok({ data: npc("n1", "Saved") }));
+
+    expect(await store.getRecord("npcs", "n1")).toBeUndefined();
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("stores nothing for a write in a root record the device does not keep (a player's root record)", async () => {
+    await writeThrough(
+      { method: "PATCH", url: "http://api.test/npcs/p1" },
+      ok({ data: npc("p1", "Player's", "P"), included: [npc("p2", "Other", "P")] }),
+    );
+    await writeThrough(
+      { method: "POST", url: "http://api.test/roots/P/npcs" },
+      ok({ data: { type: "npcs", id: "p3", attributes: { name: "No relationship" } } }),
+    );
+
+    expect(await store.getRecord("npcs", "p1")).toBeUndefined();
+    expect(await store.getRecord("npcs", "p2")).toBeUndefined();
+    expect(await store.getRecord("npcs", "p3")).toBeUndefined();
+    expect(await store.linksFrom("p1")).toEqual([]);
+  });
+
+  it("never overwrites a record that has a waiting change (a queue entry targets it) or a base", async () => {
+    await store.putRecord({ type: "npcs", id: "n1", rootId: "C", resource: npc("n1", "Mine"), updatedAt: null });
+    await store.enqueue({
+      rootId: "C",
+      method: "POST",
+      path: "npcs",
+      body: { data: npc("n1", "Mine") },
+      base: null,
+    });
+    await store.putRecord({
+      type: "npcs",
+      id: "n2",
+      rootId: "C",
+      resource: npc("n2", "Mine"),
+      updatedAt: null,
+      base: npc("n2", "Base"),
+    });
+
+    await writeThrough(
+      { method: "PATCH", url: "http://api.test/npcs/n1" },
+      ok({ data: npc("n1", "Server"), included: [npc("n2", "Server")] }),
+    );
+
+    expect((await store.getRecord("npcs", "n1"))?.resource.attributes.name).toBe("Mine");
+    expect((await store.getRecord("npcs", "n2"))?.resource.attributes.name).toBe("Mine");
+  });
+
+  it("updates the links of the written record from the answer's relationships", async () => {
+    await store.putRecord({ type: "npcs", id: "n1", rootId: "C", resource: npc("n1", "A"), updatedAt: null });
+    await store.putLink({ fromType: "npcs", fromId: "n1", toType: "npcs", toId: "old", kind: "friends", props: {} });
+
+    await writeThrough(
+      { method: "PATCH", url: "http://api.test/npcs/n1" },
+      ok({
+        data: {
+          ...npc("n1", "A"),
+          relationships: {
+            root: { data: { type: "roots", id: "C" } },
+            friends: { data: [{ type: "npcs", id: "new" }] },
+            portrait: { data: { type: "artworks", id: "a1" } },
+          },
+        },
+      }),
+    );
+
+    const links = (await store.linksFrom("n1")).map((link) => `${link.kind}:${link.toId}`).sort();
+    expect(links).toEqual(["friends:new", "portrait:a1", "root:C"]);
+  });
+
+  it("removes the old cached image when an online write changes an artwork's image URL", async () => {
+    const images = cache.caches.get("wyrdli-images")!;
+    images.set("http://api.test/artworks/a1/image?v=1", {});
+    await store.putRecord({
+      type: "artworks",
+      id: "a1",
+      rootId: "C",
+      resource: artwork("a1", "http://api.test/artworks/a1/image?v=1"),
+      updatedAt: null,
+    });
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: true, status: 200 })),
+    );
+
+    await writeThrough(
+      { method: "PATCH", url: "http://api.test/artworks/a1" },
+      ok({ data: artwork("a1", "http://api.test/artworks/a1/image?v=2") }),
+    );
+
+    expect(images.has("http://api.test/artworks/a1/image?v=1")).toBe(false);
+  });
+});

package/src/offline/config.ts

@@ -0,0 +1,229 @@
+import { attachBrowserOnlineEvents, getOfflineState, setOfflineState } from "./state";
+import type { DeviceStore } from "./store/DeviceStore";
+import {
+  DEFAULT_DEVICE_WORKER_URL,
+  DEFAULT_SQLITE_MODULE_URL,
+  NeedsConnectionError,
+  type OfflineConfig,
+} from "./types";
+
+// Kept free of store, worker and React imports: `directFetch` reads `isOfflineConfigured()` on
+// every request, so this module is the only offline code an app that never opts in loads.
+
+let _config: OfflineConfig | null = null;
+let _opener: ((userId: string) => Promise<DeviceStore>) | null = null;
+// Registered by the `./offline` entry (configure.ts), so the store code is reachable only from it.
+let _defaultOpener: ((userId: string) => Promise<DeviceStore>) | null = null;
+const _stores = new Map<string, Promise<DeviceStore>>();
+// Users whose device store must not be opened again (logged out) until they sign in again.
+const _blockedUsers = new Set<string>();
+// Per user: whether offline mode is on on this device (`requireOptIn`). Read from localStorage
+// once, since `isOfflineConfigured()` runs on every request.
+const _enabledCache = new Map<string, boolean>();
+
+const ENABLED_KEY_PREFIX = "nja-offline-enabled:";
+const LAST_SYNC_KEY_PREFIX = "nja-offline-last-sync:";
+
+function readStorage(key: string): string | null {
+  try {
+    return typeof localStorage === "undefined" ? null : localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function writeStorage(key: string, value: string | null): void {
+  try {
+    if (typeof localStorage === "undefined") return;
+    if (value === null) localStorage.removeItem(key);
+    else localStorage.setItem(key, value);
+  } catch {
+    // Storage can be blocked or full: the switch then lasts for this page only.
+  }
+}
+
+/**
+ * The signed-in user's device store cannot be used: it could not be opened (opfs-sahpool holds
+ * one connection per origin, so a second tab cannot open it) or the user logged out. A request
+ * answered from the device copy then needs a connection (503 "needs-connection").
+ */
+export class DeviceStoreUnavailableError extends NeedsConnectionError {
+  constructor(message: string = "The device copy is not available in this tab") {
+    super(message);
+    this.name = "DeviceStoreUnavailableError";
+  }
+}
+
+/**
+ * This browser cannot keep the device copy at all: not a secure context (https or `localhost`),
+ * no private file storage (`navigator.storage.getDirectory`), or the worker reports the OPFS
+ * APIs missing. Offline mode switches off for the page (`markOfflineUnavailable`). A failure on
+ * a browser that can keep the copy (the file held by another tab) is a `DeviceStoreUnavailableError`.
+ */
+export class OfflineUnavailableError extends DeviceStoreUnavailableError {
+  constructor(reason: string) {
+    super(`Offline mode isn't available in this browser: ${reason}`);
+    this.name = "OfflineUnavailableError";
+  }
+}
+
+/**
+ * Switches offline mode off for this page, once: one console warning, `available: false` in the
+ * offline state. From then on `isOfflineConfigured()` answers false, so no request, sync, drain,
+ * write-through or lock check touches the device copy again.
+ */
+export function markOfflineUnavailable(error: OfflineUnavailableError): void {
+  if (!getOfflineState().available) return;
+  console.warn(`[offline] ${error.message}. Offline mode is off in this browser.`);
+  setOfflineState({ available: false });
+}
+
+/** Whether this browser can keep the device copy (true until found otherwise). */
+export function isOfflineAvailable(): boolean {
+  return getOfflineState().available;
+}
+
+/** Logout: the user's store is never opened again in this page until `unblockOfflineStore`. */
+export function blockOfflineStore(userId: string): void {
+  _blockedUsers.add(userId);
+  _stores.delete(userId);
+}
+
+/** A sign-in (`onUserSignedIn`): the user's store may be opened again. */
+export function unblockOfflineStore(userId: string): void {
+  _blockedUsers.delete(userId);
+}
+
+export function isOfflineStoreBlocked(userId: string): boolean {
+  return _blockedUsers.has(userId);
+}
+
+/** Opts the app into offline mode. Without this call nothing offline runs. */
+export function configureOffline(config: OfflineConfig): void {
+  _config = config;
+  attachBrowserOnlineEvents();
+  refreshOfflineDeviceState();
+}
+
+/**
+ * Configured, the browser can keep the device copy (see `markOfflineUnavailable`), and offline
+ * mode is on on this device for the signed-in user (see `requireOptIn`).
+ */
+export function isOfflineConfigured(): boolean {
+  return _config !== null && isOfflineAvailable() && isOfflineEnabledOnDevice(_config.getUserId());
+}
+
+/**
+ * Whether offline mode is on on this device for `userId`. Always true without
+ * `OfflineConfig.requireOptIn`; otherwise the stored switch, false with no user.
+ */
+export function isOfflineEnabledOnDevice(userId?: string | null): boolean {
+  if (!_config?.requireOptIn) return true;
+  if (!userId) return false;
+  let enabled = _enabledCache.get(userId);
+  if (enabled === undefined) {
+    enabled = readStorage(ENABLED_KEY_PREFIX + userId) === "1";
+    _enabledCache.set(userId, enabled);
+  }
+  return enabled;
+}
+
+/** Stores the device switch for `userId` (`turnOnOffline` / `turnOffOffline`). */
+export function setOfflineEnabledOnDevice(userId: string, enabled: boolean): void {
+  writeStorage(ENABLED_KEY_PREFIX + userId, enabled ? "1" : null);
+  _enabledCache.set(userId, enabled);
+}
+
+/** When `userId`'s last full sync on this device finished (epoch ms), or null. */
+export function readOfflineLastSync(userId: string): number | null {
+  const value = Number(readStorage(LAST_SYNC_KEY_PREFIX + userId));
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
+/** Stores, or with null removes, when `userId`'s last full sync finished. */
+export function writeOfflineLastSync(userId: string, at: number | null): void {
+  writeStorage(LAST_SYNC_KEY_PREFIX + userId, at === null ? null : String(at));
+}
+
+/**
+ * Reads the device switch and the last sync time of the signed-in user into the offline state
+ * (`enabled`, `lastSyncedAt`). Does nothing before `configureOffline`.
+ */
+export function refreshOfflineDeviceState(): void {
+  if (!_config) return;
+  const userId = _config.getUserId();
+  if (userId) _enabledCache.delete(userId);
+  setOfflineState({
+    enabled: isOfflineEnabledOnDevice(userId),
+    lastSyncedAt: userId ? readOfflineLastSync(userId) : null,
+  });
+}
+
+export function getOfflineConfig(): OfflineConfig {
+  if (!_config) throw new Error("Offline mode is not configured. Call configureOffline() first.");
+  return _config;
+}
+
+/** The browser opener, set by the `./offline` entry's `configureOffline`. */
+export function setDefaultDeviceStoreOpener(opener: (userId: string) => Promise<DeviceStore>): void {
+  _defaultOpener = opener;
+}
+
+/** The URL the device worker loads SQLite from (`OfflineConfig.sqliteModuleUrl`). */
+export function getSqliteModuleUrl(): string {
+  return _config?.sqliteModuleUrl ?? DEFAULT_SQLITE_MODULE_URL;
+}
+
+/** The URL the device worker is started from (`OfflineConfig.deviceWorkerUrl`). */
+export function getDeviceWorkerUrl(): string {
+  return _config?.deviceWorkerUrl ?? DEFAULT_DEVICE_WORKER_URL;
+}
+
+/** Replaces how a user's device store is opened (tests pass `openMemoryDeviceStore`). */
+export function setDeviceStoreOpener(opener: ((userId: string) => Promise<DeviceStore>) | null): void {
+  _opener = opener;
+  _stores.clear();
+}
+
+/**
+ * The signed-in user's device store, opened once per user id. Only the signed-in user's file is
+ * ever opened; with no signed-in user the request needs a connection.
+ */
+export async function getOfflineStore(): Promise<DeviceStore> {
+  const userId = getOfflineConfig().getUserId();
+  if (!userId) throw new NeedsConnectionError("No signed-in user");
+  if (!isOfflineEnabledOnDevice(userId)) throw new DeviceStoreUnavailableError("Offline mode is off on this device");
+  if (_blockedUsers.has(userId)) throw new DeviceStoreUnavailableError("The device copy was deleted at logout");
+  if (!isOfflineAvailable()) throw new OfflineUnavailableError("it was found unable to keep the device copy");
+
+  let store = _stores.get(userId);
+  if (!store) {
+    const opener = _opener ?? _defaultOpener;
+    if (!opener) throw new Error("No device store opener: configure offline mode through the ./offline entry.");
+    store = opener(userId).catch((error) => {
+      if (error instanceof OfflineUnavailableError) markOfflineUnavailable(error);
+      if (error instanceof NeedsConnectionError) throw error;
+      console.warn("[offline] the device copy could not be opened", error);
+      throw new DeviceStoreUnavailableError(
+        `The device copy could not be opened: ${String((error as Error)?.message ?? error)}`,
+      );
+    });
+    _stores.set(userId, store);
+    store.catch(() => _stores.delete(userId));
+  }
+  return store;
+}
+
+/** Forgets the opened store of a user (logout, deleted file). */
+export function forgetOfflineStore(userId: string): void {
+  _stores.delete(userId);
+}
+
+/** Test helper: back to "not configured". */
+export function resetOfflineConfig(): void {
+  _config = null;
+  _opener = null;
+  _stores.clear();
+  _blockedUsers.clear();
+  _enabledCache.clear();
+}

package/src/offline/configure.ts

@@ -0,0 +1,14 @@
+import { configureOffline as configureOfflineLayer, setDefaultDeviceStoreOpener } from "./config";
+import type { OfflineConfig } from "./types";
+
+/**
+ * Opts the app into offline mode (the `./offline` entry's `configureOffline`). It also registers
+ * the browser device-store opener, so the store, the worker and SQLite are reachable only from
+ * this entry, never from the request path every other entry shares.
+ */
+export function configureOffline(config: OfflineConfig): void {
+  setDefaultDeviceStoreOpener((userId) =>
+    import("./store/lifecycle").then((lifecycle) => lifecycle.openDeviceStore(userId)),
+  );
+  configureOfflineLayer(config);
+}

package/src/offline/device-switch.ts

@@ -0,0 +1,75 @@
+import {
+  forgetOfflineStore,
+  getOfflineConfig,
+  getOfflineStore,
+  isOfflineAvailable,
+  setOfflineEnabledOnDevice,
+  writeOfflineLastSync,
+} from "./config";
+import { setOfflineState } from "./state";
+import { deleteImagesCaches } from "./sync/artwork-cache";
+import { stopOfflineRuntime } from "./sync/runtime";
+
+function signedInUserId(): string {
+  const userId = getOfflineConfig().getUserId();
+  if (!userId) throw new Error("No signed-in user");
+  return userId;
+}
+
+/**
+ * Turns offline mode on on this device for the signed-in user (`OfflineConfig.requireOptIn`).
+ * It does not start the runtime: the app starts it once `enabled` is true in the offline state.
+ */
+export async function turnOnOffline(): Promise<void> {
+  const userId = signedInUserId();
+  setOfflineEnabledOnDevice(userId, true);
+  setOfflineState({ enabled: true });
+  try {
+    // Asks the browser not to evict the device copy. Best effort only.
+    await navigator.storage?.persist?.();
+  } catch {
+    // Ignored: the copy works without it.
+  }
+}
+
+/**
+ * Turns offline mode off on this device for the signed-in user and deletes this device's copy
+ * (database and cached images). Refuses, changing nothing, while the copy has changes still to
+ * send: the answer then carries how many.
+ */
+export async function turnOffOffline(): Promise<{ turnedOff: true } | { turnedOff: false; pending: number }> {
+  const userId = signedInUserId();
+
+  if (isOfflineAvailable()) {
+    let pending = 0;
+    try {
+      const store = await getOfflineStore();
+      pending = (await store.queue()).length;
+    } catch {
+      // The copy cannot be opened here (held by another tab): the marker file written while
+      // changes wait still says whether deleting it would lose any. The count is then unknown: 1.
+      const { hasUnsentChanges } = await import("./store/lifecycle");
+      if (await hasUnsentChanges(userId).catch(() => false)) pending = 1;
+    }
+    if (pending > 0) return { turnedOff: false, pending };
+  }
+
+  // Off first, so a sync still running cannot open, and so recreate, the deleted file.
+  setOfflineEnabledOnDevice(userId, false);
+
+  if (isOfflineAvailable()) {
+    stopOfflineRuntime();
+    try {
+      const { deleteDeviceStore } = await import("./store/lifecycle");
+      await deleteDeviceStore(userId);
+      await deleteImagesCaches();
+    } catch (error) {
+      console.warn("[offline] the device copy could not be deleted", error);
+    }
+    forgetOfflineStore(userId);
+  }
+
+  writeOfflineLastSync(userId, null);
+  setOfflineState({ enabled: false, syncProgress: null, lastSyncedAt: null, rootCount: null });
+  return { turnedOff: true };
+}